Basic Information

Endpoint Overview

GET /api/v1/events - fetch events with support for filters (filter), projections (select), deduplication (distinct), and pagination (offset/limit).
GET /api/v1/event_counts - aggregated event counts; supports filter and unique counting with distinct.
GET /api/v1/events_schema - list of available fields (name, type, nullable) for dynamic query building.

You must provide ONE of the following to scope your query:

pixel_id (string, uuid) - Query events for a specific pixel. example: pixel_id=7b63468b-c4f2-4c3c-02d5-c82f977cf308
project_id (string, uuid) - Query events across all pixels in a project (organization). example: project_id=1d7b5e3c-7a9e-4e31-91a8-0b2d9f2b7a10
organization_id (string, uuid) - Query events across all pixels in a master organization. example: organization_id=a2e1f8a8-1b3a-4c1c-9c0f-2b6a1d9f3f11

Priority: If multiple are provided, pixel_id takes precedence over project_id, which takes precedence over organization_id.

Choose ONE format for specifying the time range:

Option A: Milliseconds (recommended for programmatic use)

start_ms (integer, int64) - Start of interval in Unix Epoch milliseconds.
end_ms (integer, int64) - End of interval in Unix Epoch milliseconds. example: start_ms=1759492800000&end_ms=1759496400000

Option B: Human-readable (convenient for manual queries)

start_time (string) - Start of interval. Accepts RFC3339, YYYY-MM-DD, or Unix timestamp.
end_time (string) - End of interval. Accepts RFC3339, YYYY-MM-DD, or Unix timestamp. examples:
- start_time=2024-01-15&end_time=2024-01-16
- start_time=2024-01-15T00:00:00Z&end_time=2024-01-15T23:59:59Z

select (string, comma-separated) - List of fields to return. example: select=email,first_name,last_name
filter (string, comma-separated) - Filter expressions in the form field:op:value. Operators: eq, ne, gt, gte, lt, lte, like. examples:
- filter=resolved:eq:true - Only identity-enriched events
- filter=event_type:eq:purchase
distinct (string, comma-separated) - Fields for deduplication/unique counting. examples:
- distinct=email
- distinct=email,cookie_id

Time window: The interval between start and end must not exceed 25 hours.
Pagination: Use offset and limit for paging; valid limit range is 1...1000.
Filters: Format is field:op:value; URL-encode colons and special characters if present.
Deduplication: The distinct parameter removes duplicates by the specified fields and affects the result of /api/v1/event_counts.
Authentication: Every request must include the X-API-Key header; invalid keys result in 401 Unauthorized.
Rate limiting: On 429 Too Many Requests, reduce request frequency and honor Retry-After.