Count and break down one day of events

get

https://api.delivr.ai/api/v3/events/web_event/counts

Count a project's or one pixel's website events over a window of up to 24 hours, and break the counts down by up to two fields. Use it to see how much traffic a day carried and where it came from, before you query the events themselves.

Counts only, and not billed. The response carries counts and category values, never identifiers: no event IDs, browser cookie IDs, IP addresses, URLs, hashed emails, or person or company fields. The route bills nothing, whatever it returns.

Three measures, counted over the whole window in totals and for each group:

events: the number of events.
visitors: the number of distinct browsers, by browser cookie. Events without a cookie are not counted here.
resolved: the number of events resolved to a person.

Top groups. groups holds the top limit groups, at most 50, largest first by order_by. Groups with the same count come in ascending order of their values. totals always covers every matching event, not only the groups returned. Without group_by, groups is empty. Each group carries its field values under key, next to its measures, for example {"key": {"ip_country": "NL"}, "events": 1002, "visitors": 14, "resolved": 0}. So group_by=resolved gives groups such as {"key": {"resolved": true}, "events": 12, "visitors": 3, "resolved": 12}. A value the events did not carry, such as an ip_country that could not be placed, is null.

Browser ranking. group_by=browser ranks individual browsers by activity. Each browser is returned as an integer rank in the ordered result, starting at 1, never as its cookie ID. Events without a browser cookie form one group whose browser is null, and it takes no rank. A rank means nothing outside its response: rank 1 in two responses need not be the same browser.

Limits. The window is at most 24 hours and starts no more than 30 days ago. One request can also read only so many stored events: a window too large for the project or pixel returns 422 with code scan_too_large, and its message gives both numbers, how many events the request would read and the limit. Narrow to one pixel, or shorten the window.

Errors carry a human-readable error and a machine-readable code. Branch on code, not on the message.

Example. The top three countries by events on one day:

GET /api/v3/events/web_event/counts?project_id=3f2b8c1e-5d4a-4e7b-9a6c-1b2d3e4f5a6b&start_ms=1792022400000&end_ms=1792108800000&group_by=ip_country&limit=3

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

project_id

string

The project whose events to count, across all its pixels. Required unless you name a pixel_id.

pixel_id

string

Narrows the counts to one of the project's pixels. Optional when you name project_id, required when you do not.

start_ms

int64

required

Start of the window, in milliseconds since the epoch. No more than 30 days before the time of the request.

end_ms

int64

required

End of the window, in milliseconds since the epoch. At most 24 hours (86,400,000 ms) after start_ms.

filter

string

Filter expression using <field>:<op>:<value> syntax, the same grammar as the tier routes. Every field it names must be one the web_event tier carries, as listed by GET /api/v3/events/web_event/schema; any other field returns 400.

group_by

string

Comma-separated fields to break the counts down by, at most two, from pixel_id, event_type, ip_country, is_bot, bot_type, resolved, gpc and browser. browser groups by individual browser and returns each one as a rank. Omit group_by for totals alone, with an empty groups array.

order_by

string

enum

Defaults to events

The measure that orders the groups, largest first.

Allowed:

limit

integer

1 to 50

Defaults to 10

How many groups to return, from the top. Above 50 returns 400.

Responses

401

Missing or invalid API key.

429

Rate limited. Wait for the Retry-After header, in seconds, then retry.

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Totals for the window, and the top groups.

400Invalid query: a missing start_ms or end_ms, a window longer than 24 hours or starting more than 30 days ago, neither project_id nor pixel_id, a filter naming a field the web_event tier does not carry, more than two or an unknown group_by field, an unknown order_by, or a limit above 50.

404Project or pixel not found, or not in your organization.

422With code scan_too_large: the window holds more stored events than one request can read for this project or pixel. The message gives both numbers: how many events the request would read, and the limit. Narrow to one pixel, or shorten the window. Check code to tell this apart from any other 422.

503Counts are temporarily unavailable. Retry shortly.