--- title: "List events" method: GET path: "/events" tags: ["events"] --- # List events `GET /events` ## Request - Base URL: `https://api.pscrpt.com/v1` - URL: `https://api.pscrpt.com/v1/events` - Auth: one of: - HTTP bearer - OAuth 2 - Authorization code: `https://api.pscrpt.com/oauth/authorize` - Token URL: `https://api.pscrpt.com/oauth/token` scopes: `events:read` There may be a delay of several seconds between writing an event and its appearance in this list. `filter[occurred_at][gte]` and `filter[occurred_at][lt]` are required and may be at most 1 day apart; otherwise the request is 400 `parameter_invalid`. To sync every event, see [Syncing](/docs/pagination#syncing). Expanding a large page can exceed the 5 MiB response cap and return 400 `expand_limit_exceeded`. Request a smaller `page[limit]` or fewer expansions. ## Query parameters - `page[limit]` integer - `page[after]` string - `filter[type]` string - `filter[type][in]` string[] - `filter[profile_id]` string - `filter[profile_id][in]` AudienceProfileId[] - `filter[occurred_at][gte]` string, date-time, required - `filter[occurred_at][lt]` string, date-time, required - `filter[dedupe_id]` string - `sort` string - `expand` string[] ## Headers - `Postscript-Version` string, date ## Response `200` One page of events. - EventPageEnvelope - `data` Event[], required - `currency` string, nullable, required: Non-null exactly when `value` is. - `dedupe_id` string, nullable, required: First write wins for 48 hours, property-scoped. See [Idempotency & retries](/docs/idempotency). - `event_type` EventsMetricsEventType: The registered meaning and observed schema of an event type. - `description` string, nullable, required: Writable on custom metrics only. - `first_seen_at` string, date-time, required - `id` string, required: EventType ID (`etyp_*`). - `name` string, required: The event type this metric aggregates, e.g. `order.completed`. - `object` 'event_type', required - `schema` object, required: Discovered property types, `{property path: type}`. Fills in as events arrive; a path observed with conflicting types reads `mixed`. - `source` string, nullable, required: Originating integration (`shopify`, `api`, `sdk`). - `system` boolean, required: True for platform-owned standard metrics. - `id` string, required - `object` 'event', required - `occurred_at` string, date-time, required - `profile` Profile - `attributes` object, required - `consents` Consent[]: Stored marketing-consent states for the profile's identifiers. - `channel` string, required - `consented_at` string, date-time, required - `id` string, required - `identifier` Identifier - `created_at` string, date-time, required - `display_value` string, required - `id` string, required - `is_primary` boolean, required - `object` 'identifier', required - `profile_id` string, required - `source` string, required - `type` string, required - `updated_at` string, date-time, required - `value` string: Requires the `identifiers:read_value` scope. - `verified_at` string, date-time, required - `identifier_id` string, required - `method` string, required: How consent was collected. - `method_detail` string, nullable, required - `object` 'consent', required - `profile_id` string, required - `source` string, required: Origin derived from the credential. - `source_reference` string, nullable, required - `status` 'subscribed' | 'unsubscribed' | 'never_subscribed' | 'pending' | 'expired', required - `updated_at` string, date-time, required - `created_at` string, date-time, required - `id` string, required - `identifier_ids` IdentifierId[], required - `identifiers` Identifier[] - `created_at` string, date-time, required - `display_value` string, required - `id` string, required - `is_primary` boolean, required - `object` 'identifier', required - `profile_id` string, required - `source` string, required - `type` string, required - `updated_at` string, date-time, required - `value` string: Requires the `identifiers:read_value` scope. - `verified_at` string, date-time, required - `location` Location, required - `city` string, nullable - `country` string, nullable: ISO 3166-1 alpha-2. - `region` string, nullable - `timezone` string, nullable: IANA time zone name. - `zip` string, nullable - `merged_into` string, required - `object` 'profile', required - `profile_ref` string: Property-scoped compact reference, present for properties enabled for the rollout. It is not authorization or merge evidence. - `status` 'active' | 'merged' | 'redacted', required - `tags` string[], required: Managed in the Postscript app and by the Shopify customer sync. - `updated_at` string, date-time, required - `profile_id` string, nullable, required: Null only for anonymous events not yet linked to a profile. - `properties` object, required - `received_at` string, date-time, required - `source` string, required - `type` string, required: Lowercase dot notation, e.g. `order.completed`. Underscores are rewritten as dots. Platform namespaces such as `sms.*` and `profile.*` are reserved. - `value` string, nullable, required: Decimal string. - `meta` Meta, required - `as_of` string, date-time - `livemode` boolean, required - `page` PageMeta - `limit` integer, required - `next_cursor` string, nullable, required: Pass as `page[after]`. Null on the last page. - `request_id` string, required - `resolved_from` string: The merged-away profile ID the request addressed; `data` holds the survivor. - `revision` string, date, required ## Other responses - `400`: Malformed input, an unknown parameter, an unsupported filter, sort, or expand, or a mistyped ID. - `401`: Missing or invalid API key. - `403`: The key lacks the required scope. - `429`: Rate limit exceeded. - `500`: Internal error. - `502`: Upstream provider failure. - `503`: A dependency is temporarily unavailable; retry unchanged after `retry_after_ms`. ## Changes - **2026-10-09** `8dfa57319d25`: 2 breaking, 1 warning - added the new required `query` request parameter `filter[occurred_at][lt]` - the `query` request parameter `filter[occurred_at][gte]` became required - deleted the `query` request parameter `filter[occurred_at][lte]` - **2026-10-07** `2670c64aaec7`: 1 info - endpoint added [Operation history](https://skmtc.dev/pscrpt/apis/postscript-native-api-beta/changes/events/get.md) --- [API](https://skmtc.dev/pscrpt/apis/postscript-native-api-beta.md) - [All operations](https://skmtc.dev/pscrpt/apis/postscript-native-api-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/pscrpt/apis/postscript-native-api-beta/revisions/882458ee1f36?raw)