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
include_total
boolean
default:false

Send true to count every matching event, so total_count is exact on every page of a property_filters request. Only the string true turns it on: 1, yes, and TRUE do not.

Without it, a property_filters request skips the count. total_count is then exact on the last page and a lower bound on every page before it, flagged by total_count_is_lower_bound. has_more is exact either way.

The count reads event_data for every event in the range a second time, so the request takes longer. If either read fails or times out, the response is 503. Without property_filters the count always runs, and this parameter changes nothing.

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

Matching events in the whole date range, not in this page. Always exact without property_filters, and exact with include_total=true.

With property_filters and no include_total, it is exact on the last page. On an earlier page it is a lower bound, offset + returned_count + 1, and total_count_is_lower_bound is true. A page past the end, with no rows at a non-zero offset, reports 0 as a lower bound.

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.

total_count_is_lower_bound
boolean

Present, and true, only when total_count is a lower bound rather than the exact total. Absent otherwise, and never sent as false. To get the exact total, page until has_more is false, or send include_total=true.

coverage
object
property_filters
object[]

The property filters the request applied, echoed back. Absent when it applied none.

property_filter_note
string

Present only with property_filters. Explains in prose that the filter scans every event in the range, which ops exclude events without the key, and whether total_count was counted or is a lower bound. Read total_count_is_lower_bound for the flag, not this text.