Skip to main content
GET
List events

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

start_date
string<date-time>
required

Inclusive ISO 8601 start date.

end_date
string<date-time>
required

Inclusive ISO 8601 end date.

event_name
string

Comma-separated event names.

utm_source
string
utm_campaign
string
country
string

Country code.

page_path
string
property_filters
string

Filters on the event_data JSON blob, as a JSON array of {key, op, value} objects combined with AND. Up to 5. op is one of eq, neq, contains, gt, lt. Example: [{"key":"plan","op":"eq","value":"pro"},{"key":"amount","op":"gt","value":20}].

Use /events/properties to get key names. A key that is not tracked returns zero rows, which is indistinguishable from a key whose value never matches.

eq, neq and contains compare the value as text and require the key to be PRESENT — so neq EXCLUDES events that never carried the key, rather than counting them as not-equal. gt and lt compare the value as a number and ignore events whose value is missing, null, boolean, or non-numeric. A JSON string such as "12" is treated as the number 12, because event_data is untyped and the same property arrives quoted from one SDK and bare from another.

event_data has no index, so a property filter reads every event in the range. The range is therefore capped at 31 days when property_filters is present; a wider range is a 400, not a slow query.

limit
integer
default:100
Required range: 1 <= x <= 1000
offset
integer
default:0
Required range: x >= 0

Response

Successful response. Three source fields ride together during the events-source rename. attribution_source is the stable alias to read for attribution; transport_source is the stable field for transport.

events
object[]
required
total_count
integer
required

Authoritative row count for the whole date range, not for this page.

returned_count
integer
required

Rows in this page.

has_more
boolean
required

Exact. Page until it is false rather than until a page comes back short.

limit
integer
required
offset
integer
required
complete
boolean
required

Always true on a 200. A failed read is a 503, never an empty page.

coverage
object