Skip to content
Pidgely Docs

API reference · Events

List events

GEThttps://api.pidgely.com/events
View as Markdown

Recent events, newest first. Filter by email or name; paginate with after and before.

Recent events, newest first, optionally of one address or one name. Full access keys.

Authorization: Bearer pdg_…. An API key with full_access. A sending_access key gets 401 restricted_api_key.

Query parameters

Name Type Required Description
email string No Only the events of this address.
name string No Only events with this name.
limit integer No Page size (1-100). Between 1 and 100.
after string No Id of the last item of the previous page (older items). UUID.
before string No Id of the first item of the current page (newer items). UUID.

Request

This endpoint is not in the SDKs yet; call it over HTTP.

cURL
curl -X GET 'https://api.pidgely.com/events?email=ana.souza%40example.com&limit=20' \
  -H "Authorization: Bearer $PIDGELY_API_KEY"

Response

200 OK

JSON
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "event",
      "id": "0199e4a2-7b8c-7d9e-8f0a-1b2c3d4e5f61",
      "name": "trial_started",
      "email": "ana.souza@example.com",
      "contact_id": "0199d7f4-5d7b-7a2c-b4e1-9f3c2a6d8e05",
      "properties": {
        "plan": "pro",
        "trial_days": 14
      },
      "occurred_at": "2026-10-22T12:00:00Z",
      "received_at": "2026-10-22T12:00:00.184Z",
      "duplicate": false
    }
  ]
}

Response fields

Name Type Required Description
object string Yes Object type. One of list.
has_more boolean Yes Whether another page exists.
data object[] Yes Items of this page.
data[].object string Yes Object type. One of event.
data[].id string Yes Unique id (UUID). UUID.
data[].name string Yes Display name.
data[].email string Yes Email address.
data[].contact_id string | null Yes UUID.
data[].properties object (map of any) Yes Custom properties: up to 100 keys matching ^[A-Za-z_][A-Za-z0-9_]{0,49}$, values string (up to 2,000 characters), number, boolean, or null to delete.
data[].occurred_at string Yes Format: date-time.
data[].received_at string Yes Format: date-time.
data[].duplicate boolean Yes The idempotency key was already used (the original event is returned).

Errors

Errors have the shape {"statusCode", "name", "message"}. See Errors for the full list.

Status Name When
401 missing_api_key, restricted_api_key No Authorization: Bearer header, or a sending_access key called an endpoint that needs full_access.
403 invalid_api_key, validation_error The API key is invalid or revoked, or the request is not allowed for this account (unverified domain, plan limit, paused account).
422 validation_error A field is missing or invalid; message names it.
429 rate_limit_exceeded Too many requests per second. Wait for Retry-After seconds.