GET /me
Inspect current API key
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
200 | OK |
Live, hand-maintained spec rendered with Scalar. Click any endpoint and use Test Request to send a real call.
links:write scope.
curl -X POST https://api.qrindo.com/api/v1/links \
-H "Authorization: Bearer $QRINDO_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "target_url": "https://example.com/launch", "title": "Launch" }' short_url to test the redirect, then poll
/api/v1/links/{code}/stats?period=7d for analytics.
Qrindo Public API v1.0 · 157 public endpoints · Base URL: https://api.qrindo.com/api/v1
Bearer-token (API key or OAuth client_credentials) REST API for the Qrindo platform. Designed for partner products that need to mint dynamic links, render QR codes, read analytics, and subscribe to scan events.
Every request requires Authorization: Bearer <token>.
| Token kind | Format | Best for |
|---|---|---|
| API key | qrf_live_... / qrf_test_... |
Long-lived backend integrations |
| OAuth access token | JWT (RS256) | Compliance / rotation-heavy partners |
Errors generally follow RFC 7807 problem-json. Report query validation failures use application/json with timestamp, status, error and message, as documented in the report 400 responses.
{
"type": "https://qrindo.com/errors/rate_limited",
"title": "Too many requests",
"status": 429,
"code": "rate_limited",
"detail": "Rate limit exceeded: 10000 req/min per API key. Retry in 12s.",
"instance": "01HRV..."
}
Pass Idempotency-Key: <uuid> on any POST. Retrying with the same key + body
replays the cached response. Retrying with a different body returns
409 idempotency_replay_mismatch.
Per-key per-minute, with RFC 9331
headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset).
Stickers are usually printed in bulk, before anyone knows where each one
will point. Create those codes with content_type: "placeholder" and no
target_url: each one is a real, scannable code whose scan renders the
hosted "This QR code is reserved" page, which shows that code so whoever
is holding the sticker can read it back to you. target_url is null on a
reserved code, and GET /links?content_type=placeholder is the unassigned
pool.
Assigning one is an ordinary destination change: POST /links/{code}/rotate,
a PATCH /links/{code} with a target_url, or a bulk target_url on
PATCH /links/batch. The reserved page is replaced by the redirect and the
printed QR keeps working. PATCH /links/batch with
reset_to_placeholder: true is the reverse, for a sticker that comes back
or is re-sold: the code returns to the reserved page with a fresh payload,
while its title, tags, folder, QR design, scans and history stay as they
were.
The interactive reference below reads the same spec and can send real requests.
GET /me
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
200 | OK |
GET /links
Filters are applied server-side, so finding the reserved codes in a workspace of thousands does not mean paging through all of them: `?content_type=placeholder` is the unassigned pool.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cursor | query | string | — | |
limit | query | integer | — | |
q | query | string | — | Match the code or the title. |
folder_id | query | string | — | A folder id, or `none` for codes in no folder. |
content_type | query | "url" | "placeholder" | — | `url` or `placeholder` (reserved, unassigned). |
status | query | "active" | "inactive" | — | |
sort | query | "newest" | "oldest" | "most-clicks" | "name-az" | — |
Responses
| Status | Description |
|---|---|
200 | OK |
401 | Missing, malformed, expired, or revoked token. |
429 | Per-key minute window exceeded. |
POST /links
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | — |
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
qr_color | stringnull | — | |
qr_bg_color | stringnull | — | |
qr_shape | "square" | "rounded" | "dot" | "dots" | "classy" | "extra-rounded" | "diamond" | "null" | — | |
qr_logo | stringnull | — | PNG, JPEG or WebP raster image as a base64 data URI. |
qr_frame | objectnull | — | |
qr_eye_shape | "square" | "rounded" | "circle" | "leaf" | "null" | — | |
qr_eye_color | stringnull | — | |
qr_eye_ball_color | stringnull | — | |
qr_gradient_from | stringnull | — | |
qr_gradient_to | stringnull | — | |
qr_logo_shape | "rounded" | "circle" | "square" | "null" | — | |
target_url | string (uri) | — | Required for `url` links. Must be omitted when `content_type` is `placeholder`. |
content_type | "url" | "placeholder" | — | `placeholder` reserves the code for stickers printed before their destinations are known. Assign it later with `POST /links/{code}/rotate`, a `PATCH /links/{code}` carrying a `target_url`, or a bulk `target_url`. |
placeholder | object | — | Copy for the reserved page. Both text fields are optional; left out, the page falls back to its own wording and still shows the code. |
code | string | — | Optional vanity slug. 4-8 chars, [A-Za-z0-9_-]. |
title | string | — | |
active | boolean | — | |
tags | string[] | — | |
folder_id | string | — | A folder in this workspace (see `/folders`). Null or omitted leaves the code unfiled. |
Responses
| Status | Description |
|---|---|
201 | Created |
400 | Validation failed |
409 | Code conflict or idempotency mismatch |
GET /links/{code}
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes |
Responses
| Status | Description |
|---|---|
200 | OK |
404 | Resource not found. |
PATCH /links/{code}
Only the fields you send are changed. A `target_url` sent to a reserved (`placeholder`) code assigns it, exactly like a rotate.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes |
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
qr_color | stringnull | — | |
qr_bg_color | stringnull | — | |
qr_shape | "square" | "rounded" | "dot" | "dots" | "classy" | "extra-rounded" | "diamond" | "null" | — | |
qr_logo | stringnull | — | PNG, JPEG or WebP raster image as a base64 data URI. |
qr_frame | objectnull | — | |
qr_eye_shape | "square" | "rounded" | "circle" | "leaf" | "null" | — | |
qr_eye_color | stringnull | — | |
qr_eye_ball_color | stringnull | — | |
qr_gradient_from | stringnull | — | |
qr_gradient_to | stringnull | — | |
qr_logo_shape | "rounded" | "circle" | "square" | "null" | — | |
target_url | string (uri) | — | Assigns a reserved (`placeholder`) code, turning it into a live `url` link. |
title | string | — | |
active | boolean | — | |
tags | string[] | — | Replaces the whole tag list. Cannot be combined with `add_tags` or `remove_tags`. |
add_tags | string[] | — | Merged into the tags the code already carries. |
remove_tags | string[] | — | |
folder_id | string | — | Move the code to this folder. `null` takes it out of its folder. |
Responses
| Status | Description |
|---|---|
200 | OK |
DELETE /links/{code}
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes |
Responses
| Status | Description |
|---|---|
204 | Deleted |
404 | Resource not found. |
POST /links/{code}/rotate
The printed QR never changes. On a reserved (`placeholder`) code this is how it is ASSIGNED: the code becomes a live `url` link and the reserved page is replaced by a redirect.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes |
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
target_url | string (uri) | yes |
Responses
| Status | Description |
|---|---|
200 | OK |
POST /links/batch
Returns 201 if all succeed, 207 (multi-status) on partial failure. Each item reports its own success/error. Items may mix `url` links and `placeholder` (reserved, unassigned) codes, which is how a print run is created before its destinations are known.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | — |
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
items | object[] | yes |
Responses
| Status | Description |
|---|---|
201 | All created |
207 | Partial success |
401 | Missing, malformed, expired, or revoked token. |
PATCH /links/batch
Three modes. Send `target_url` to repoint every code (a reserved code becomes a live `url` link). Send `reset_to_placeholder: true` to put codes BACK into the unassigned pool, so a returned or re-sold sticker shows the reserved page again: the content type and its payload are replaced, and the title, tags, folder, QR design, scan counters and history are left untouched. Anything else is a metadata-only update. Repoint and reset report per-code results as `{ "updated": n, "errors": [{ "code", "error" }] }`, so one bad code never aborts the batch.
Auth: BearerAuth
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
codes | string[] | yes | |
active | boolean | — | |
tags | string[] | — | Replaces the whole tag list on every code. Cannot be combined with `add_tags` or `remove_tags`. |
add_tags | string[] | — | Merged into the tags each code already carries, per code. |
remove_tags | string[] | — | |
folder_id | string | — | |
target_url | string (uri) | — | Repoint every code here. Mutually exclusive with `reset_to_placeholder`. |
reset_to_placeholder | boolean | — | Return every code to the unassigned pool (the reserved page). Mutually exclusive with `target_url`. |
claim_enabled | boolean | — | Only valid together with `reset_to_placeholder: true`. Whether the fresh reserved page carries the claim form. Explicit because assigning a code discards its previous setting. |
Responses
| Status | Description |
|---|---|
200 | OK |
207 | Partial success |
400 | `reset_to_placeholder` sent with `target_url`, or `claim_enabled` sent without it |
DELETE /links/batch
Auth: BearerAuth
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
codes | string[] | yes |
Responses
| Status | Description |
|---|---|
200 | OK |
207 | Partial success |
POST /links/import
Accepts text/csv or multipart/form-data (a `file` field). CSV columns: target_url,code,title,tags (tags pipe-separated).
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
201 | All imported |
207 | Partial import |
413 | Upload exceeds the size limit. |
GET /qr/{codeAndExt}
`png` and `svg` are screen images. `pdf` and `eps` are print files: sized in millimetres by the print parameters, with outlined text, and described on the `X-Qr-Print` response header (trim, page, bleed, code size, colour). A size that cannot print is refused with 400 and the reason.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
codeAndExt | path | string | yes | |
size | query | integer | — | |
fg | query | string | — | |
bg | query | string | — | |
ec | query | "L" | "M" | "Q" | "H" | — | |
trimW | query | number | — | Finished width of the printed piece, in `unit`. A width alone makes a square piece. |
trimH | query | number | — | Finished height of the printed piece, in `unit`. |
unit | query | "mm" | "cm" | — | |
bleed | query | number | — | Bleed on every side, beyond the trim, in millimetres. |
safe | query | number | — | Margin inside the trim that the code keeps clear of, in millimetres. |
qrMm | query | number | — | Width of the code on the piece, in `unit`. Omit to fill the safe area. |
colorSpace | query | "rgb" | "cmyk" | — | `cmyk` writes DeviceCMYK, with every neutral on the black plate alone. |
marks | query | "0" | "1" | — | Crop marks outside the bleed. |
Responses
| Status | Description |
|---|---|
200 | PNG, SVG, PDF or EPS bytes |
400 | A print size that cannot make a printable file, with the reason |
POST /qr/render
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
200 | Rendered image or print file |
POST /qr/batch
Renders up to 50 of your links as PNG, SVG, PDF or EPS and streams them back as a single ZIP archive, one `{code}.{format}` file each. Print files share one size, given by the print options. Codes that don't belong to the workspace are skipped.
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
200 | ZIP archive of QR images or print files |
400 | A print size that cannot make a printable file, with the reason; nothing is zipped |
404 | None of the provided codes resolved to a link |
GET /links/{code}/stats
Scans over time. `granularity` controls the bucket size; a size too fine for the window is rejected with 400 rather than silently downgraded, and a response never exceeds 1500 points.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes | |
period | query | "7d" | "30d" | "90d" | "1y" | — | |
from | query | string | — | Window start: a calendar day (YYYY-MM-DD, read in `tz`) or a full ISO instant. Instants are what make sub-day resolution reachable. |
to | query | string | — | Window end, same formats as `from`. Exclusive. |
tz | query | string | — | IANA zone every bucket and timestamp is expressed in. Defaults to UTC, which is rarely what you want if your audience is not in it. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — |
Responses
| Status | Description |
|---|---|
200 | OK |
GET /links/{code}/breakdown
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes | |
period | query | "7d" | "30d" | "90d" | "1y" | — | |
from | query | string | — | Window start: a calendar day (YYYY-MM-DD, read in `tz`) or a full ISO instant. Instants are what make sub-day resolution reachable. |
to | query | string | — | Window end, same formats as `from`. Exclusive. |
tz | query | string | — | IANA zone every bucket and timestamp is expressed in. Defaults to UTC, which is rarely what you want if your audience is not in it. |
dim | query | "country" | "device" | "os" | "browser" | "referrer" | — |
Responses
| Status | Description |
|---|---|
200 | OK |
GET /links/{code}/events
One row per recorded scan, newest first, each with its exact timestamp. Keyset-paginated: pass the previous response's `next_cursor` as `cursor`. There is no offset and no total count, both are expensive on the underlying time-series table. Individual scans are retained for 365 days.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes | |
period | query | "7d" | "30d" | "90d" | "1y" | — | |
from | query | string | — | Window start: a calendar day (YYYY-MM-DD, read in `tz`) or a full ISO instant. Instants are what make sub-day resolution reachable. |
to | query | string | — | Window end, same formats as `from`. Exclusive. |
tz | query | string | — | IANA zone every bucket and timestamp is expressed in. Defaults to UTC, which is rarely what you want if your audience is not in it. |
cursor | query | string | — | |
limit | query | integer | — | |
include_bots | query | boolean | — | Bots are excluded unless you ask for them. |
country | query | string | — | |
city | query | string | — | |
region | query | string | — | |
device | query | string | — | |
os | query | string | — | |
browser | query | string | — | |
referrer_host | query | string | — | |
visitor | query | string | — | Salted visitor hash, as returned in `visitor`. |
Responses
| Status | Description |
|---|---|
200 | OK |
GET /reports/access-history
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/account-churn
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/account-history
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/account-retention
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/acquisition
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/adoption
Operator-only platform report. Requires analytics:read; the API key resolver always selects a workspace or code, so this handler returns 404 on the reporting mount. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/ai-visibility
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/alerts/events
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/alerts
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/annotations
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/anomalies
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/attention
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/attribution
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/audit-actions
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/batches/{batchId}/curve
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
batchId | path | string | yes | |
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
days | query | integer | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/batches/production
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/batches
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
horizonDays | query | integer | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/behaviour/funnel
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
bucket | query | "day" | "week" | "month" | — | Unrecognized values fall back to day. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/behaviour/log
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
stream | query | "account" | "visitor" | — | |
name | query | string | — | |
userId | query | string | — | |
source | query | string | — |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/behaviour/logins
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
bucket | query | "day" | "week" | "month" | — | Unrecognized values fall back to day. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/behaviour/visitors
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
bucket | query | "day" | "week" | "month" | — | Unrecognized values fall back to day. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/breakdown
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
dim | query | "code" | "workspace" | "botEngine" | "country" | "city" | "region" | "device" | "os" | "browser" | "deviceModel" | "language" | "utmSource" | "utmMedium" | "utmCampaign" | "continent" | "visitorClass" | "networkType" | "channel" | "networkOrg" | "postalCode" | "visitorTimezone" | "anonymizer" | "utmTerm" | "utmContent" | "clickIdSource" | "host" | "outcome" | "variant" | "tag" | "contentType" | "referrer" | "folder" | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/campaigns
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/captured-leads/{id}
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | |
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/captured-leads
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/code-inventory
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
page | query | integer | — | |
search | query | string | — | |
ownerId | query | string | — |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/codes/{code}
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes | |
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/codes
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/cohorts
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/consumers
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/conversion-goals
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/costs
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/coverage
Requires analytics:read. Returns shared signal capture epochs and coverage gaps for the requested window. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/demand
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/designs
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/destination-health
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/destination-health/failing
The failing subset of `/reports/destination-health`, as the codes themselves rather than totals. Requires analytics:read. Read-only reporting mount: write methods return 405. Scoped to the API key workspace, optionally narrowed to an owned code. `checked` is the denominator and the only field that separates a true zero from a silence: `checked = 0` beside `failing = 0` does not mean nothing is broken, it means nothing has been looked at yet. The sweep is budgeted, so a large workspace can sit with `checked` well below `eligible` for a long time. Do not render a "0 broken" badge on that state - read `lastCheckedAt` and show nothing instead. It accepts the shared reporting query parameters, but only `limit` changes this response; the ceiling is 500 and `truncated` carries the shortfall.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/dormant-accounts
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code. Verified in production on 2026-11-09: API key requests return 200 for the caller workspace.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
minDormantDays | query | integer | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/email-deliveries
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/engagement
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/erasure
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/event-history
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
eventAction | query | string | — | |
eventAudience | query | "new" | "returning" | "unattributed" | — |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/events.csv
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | CSV download. |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/events/crawlers
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
surface | query | "marketing" | "landing" | "app" | "api" | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/events/landing-health
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/events/opt-outs
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/events
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
cursor | query | string | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/export.csv
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
panel | query | "engagement" | "pages" | "funnel" | "segments" | "attribution" | "visitors" | "cohorts" | "campaigns" | "market" | "referrers" | "demand" | "anomalies" | "seasonal" | "pipeline" | "hotLeads" | "goals" | "interactions" | "scans" | "revenue" | "codes" | "series" | "breakdown" | "geo" | "heatmap" | "live" | "aiVisibility" | "searchQueries" | "workspaces" | — | |
dim | query | string | — | |
liveWindow | query | integer | — |
Responses
| Status | Description |
|---|---|
200 | CSV download. |
302 | When panel=scans, redirects to events.csv with the remaining query parameters. |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/first-week-adoption
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/funnel
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/geo
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/goals
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/heatmap
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/hot-leads
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/interactions
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/known-visitors/unlabelled
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/known-visitors
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/latest-signups
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405. Verified in production on 2026-11-09: API key requests return 403.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/lead-funnel
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/lead-ownership
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/live
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
liveWindow | query | integer | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/log-summary
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/market
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/message-recipients
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/new-vs-returning
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/nudge-variants
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/overview
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code. Verified in production on 2026-11-09: API key requests return 200 for the caller workspace.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/pages
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/pipeline
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/placement-alignment
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
siteId | query | string | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/placements
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
siteId | query | string | — | |
includeRetired | query | "0" | "1" | "true" | "false" | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/product-activity
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/referrals/series
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/referrals
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/referrers
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/relay-health
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/reliability
Operator-only platform report. Requires analytics:read; the API key resolver always selects a workspace or code, so this handler returns 404 on the reporting mount. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/repoints/effect
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | yes | |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
version | query | integer | yes | |
spanHours | query | integer | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/repoints/effects
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
spanHours | query | integer | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/repoints/markers
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/repoints
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/report-images/{id}
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | |
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/reports/{id}
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | |
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/reports
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | |
to | query | string | — | |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
q | query | string | — | |
type | query | "bug" | "feature" | "idea" | "question" | — | |
status | query | "new" | "triaged" | "needs_info" | "planned" | "in_progress" | "shipped" | "declined" | "duplicate" | — | |
priority | query | "low" | "medium" | "high" | "urgent" | — | |
area | query | "leads" | "api" | "other" | "links" | "qr" | "analytics" | "billing" | "team" | "sites" | "relay" | "account" | — | |
assigneeId | query | string | — | |
sort | query | "newest" | "oldest" | "votes" | "updated" | — | |
cursor | query | string | — | |
openOnly | query | "true" | "false" | — | |
excludeId | query | string | — |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/retention
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/revenue
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/rules/series
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/rules
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/sales-pipeline
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405. Verified in production on 2026-11-09: API key requests return 403.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
dealId | query | string | — |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/saved-segments
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/search-queries
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/seasonal
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/security-census
Operator-only. Requires analytics:read, but an API key still receives 403: requireSuperAdmin reads session auth, which API key authentication never sets. This path is mounted for parity and is unavailable to API key integrations. Write methods return 405. Verified in production on 2026-11-09: API key requests return 403.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Operator-only. API key authentication does not set session auth, so requireSuperAdmin returns 403 even when analytics:read is present. Missing scope or an IP restriction can also return a standard problem. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/segments
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/series
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/shares
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/sites/{siteId}/units
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
siteId | path | string | yes | |
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
zone | query | string | — | |
sort | query | "visitors" | "scans" | "leads" | "label" | "change" | "lastScanAt" | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/sites/{siteId}/zones
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
siteId | path | string | yes | |
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/sites/series
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
siteIds | query | string | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/sites
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
sort | query | "name" | "visitors" | "conversions" | "scans" | "leads" | "change" | "lastScanAt" | "units" | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/subscriptions
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/summary
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/targets
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/verticals
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/visitors/{visitor}
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
visitor | path | string | yes | Visitor hash containing 4 to 16 hexadecimal characters. |
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/visitors
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
grade | query | "hot" | "warm" | "cold" | — | |
converted | query | "0" | "1" | "true" | "false" | — | |
dormantDays | query | integer | — | |
minSessions | query | integer | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/vocabulary
Requires analytics:read. Returns shared analytics vocabularies and limits. Write methods return 405.
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/whoami
Requires analytics:read. Resolves the visitor identity of this request from its network and visitor cookie. Write methods return 405.
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/workspaces/{id}
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | |
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /reports/workspaces
Requires analytics:read. Read-only reporting mount: write methods return 405. Data is scoped to the API key workspace, optionally narrowed to an owned code. Verified in production on 2026-11-09: API key requests return 200 for the caller workspace.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "today" | "yesterday" | "wtd" | "mtd" | "qtd" | "ytd" | "last_week" | "last_month" | "custom" | — | Reporting window. Custom bounds use from and to. |
from | query | string | — | Window start as YYYY-MM-DD in tz, or an ISO timestamp. |
to | query | string | — | Exclusive window end as YYYY-MM-DD in tz, or an ISO timestamp. |
tz | query | string | — | IANA time zone for calendar boundaries; defaults to UTC. |
granularity | query | "auto" | "minute" | "5min" | "hour" | "day" | "week" | — | Time bucket size; overly fine windows return 400. |
compare | query | "0" | "1" | "true" | "false" | — | Include comparison when true or 1. |
compareMode | query | "custom" | "previous" | "year" | — | Comparison baseline mode. |
compareFrom | query | string | — | Custom comparison start. |
compareTo | query | string | — | Custom comparison end. |
includeBots | query | "0" | "1" | "true" | "false" | — | Include bots when true or 1; excluded by default. |
includeInternal | query | "0" | "1" | "true" | "false" | — | Include internal visitors when true or 1; excluded by default. |
botsOnly | query | "0" | "1" | "true" | "false" | — | Count only bots when true or 1. |
botEngine | query | string | — | Shared analytics query control; applicability depends on the report. |
code | query | string | — | Narrow to a code owned by this API key workspace; another workspace code returns 404. |
workspaceId | query | string | — | Accepted by the shared validator but ignored on this mount. The API key always selects its own workspace. |
country | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
city | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
region | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
device | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
os | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
browser | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
referrerHost | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitor | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
deviceModel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
language | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmMedium | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmCampaign | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
continent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorClass | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkType | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorBucket | query | "people" | "crawlers" | "automated" | "unknown" | — | Shared analytics query control; applicability depends on the report. |
channel | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
networkOrg | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
asn | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
postalCode | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
visitorTimezone | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
anonymizer | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmTerm | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
utmContent | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
clickIdSource | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
host | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
outcome | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
variant | query | string | — | Segment clause: a bare value or an operator such as in:JO,AE, not:JO, contains:amm or isNull:. |
limit | query | integer | — | Maximum rows for handlers that accept a row limit. |
offset | query | integer | — | List page offset for handlers that paginate. |
segmentId | query | string | — | Saved segment applied underneath explicit population and segment filters. |
folderId | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
tag | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
contentType | query | string | — | Accepted by the shared validator but ignored by the API key scope resolver. |
sort | query | "name" | "createdAt" | "visitors" | "conversions" | "scans" | "sessions" | "leads" | "codes" | "lastActivityAt" | — |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Invalid report query parameters. Shared analytics validation returns a JSON error envelope; public API validation can return a standard problem. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
405 | The reporting API is read-only. Authenticated requests with analytics:read using write methods return 405 before shared-factory handlers run. |
429 | Per-key minute window exceeded. |
GET /events
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cursor | query | string | — | |
limit | query | integer | — | |
from | query | string (date-time) | — | |
to | query | string (date-time) | — | |
code | query | string | — |
Responses
| Status | Description |
|---|---|
200 | OK |
POST /public/preview
Auth: public
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
target_url | string (uri) | yes |
Responses
| Status | Description |
|---|---|
200 | Disposable short link + QR |
429 | Per-key minute window exceeded. |
GET /public/stats/{code}
Auth: public
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes |
Responses
| Status | Description |
|---|---|
200 | OK |
404 | Resource not found. |
429 | Per-key minute window exceeded. |
GET /public/preview/{codeAndExt}
Renders the QR for a code created by `POST /public/preview`. Unauthenticated and rate-limited. The preview expires 10 minutes after creation, after which this returns 404.
Auth: public
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
codeAndExt | path | string | yes |
Responses
| Status | Description |
|---|---|
200 | QR image |
404 | Resource not found. |
GET /public/platform-stats
Lifetime totals powering the marketing site's live numbers. Unauthenticated, rate-limited, and served from a 5-minute cache - `cached: true` marks a response served from it. Scans are lifetime per-link counters, so the number never decreases as old scan events age out of retention.
Auth: public
Responses
| Status | Description |
|---|---|
200 | OK |
GET /folders
Every folder in the workspace, oldest first, each with the number of live codes filed in it.
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
200 | OK |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
POST /folders
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | — |
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
color | string | — |
Responses
| Status | Description |
|---|---|
201 | Created |
400 | Validation failed |
PATCH /folders/{id}
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
name | string | — | |
color | string | — |
Responses
| Status | Description |
|---|---|
200 | OK |
404 | Resource not found. |
DELETE /folders/{id}
The codes filed in it are NOT deleted. They become unfiled.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Responses
| Status | Description |
|---|---|
204 | Deleted |
404 | Resource not found. |
GET /brand-kits
Read all brand kits in the token's workspace. Requires the `links:read` scope.
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
200 | OK |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
429 | Per-key minute window exceeded. |
GET /brand-kits/{id}
Read a brand kit in the token's workspace. Requires the `links:read` scope.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Brand kit id (ULID). |
Responses
| Status | Description |
|---|---|
200 | OK |
400 | Validation failed. |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
404 | Resource not found. |
429 | Per-key minute window exceeded. |
GET /qr-designs
Read all saved QR designs in the token's workspace. Requires the `links:read` scope.
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
200 | OK |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
429 | Per-key minute window exceeded. |
GET /domains
Read custom domains in the token's workspace, including ownership status and usability. Requires the `links:read` scope. DNS verification challenges and records are omitted.
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
200 | OK |
401 | Missing, malformed, expired, or revoked token. |
403 | Token does not carry the required scope or IP. |
429 | Per-key minute window exceeded. |
GET /webhooks
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
200 | OK |
401 | Missing, malformed, expired, or revoked token. |
POST /webhooks
The `secret` is returned once; use it to verify the Qrindo-Signature header (t=...,v1=HMAC-SHA256("{t}.{rawBody}")).
Auth: BearerAuth
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
url | string (uri) | yes | |
events | "scan.created" | "link.created" | "link.updated" | "link.deleted"[] | yes | |
active | boolean | — |
Responses
| Status | Description |
|---|---|
201 | Created (secret returned once) |
400 | Validation failed. |
402 | Plan webhook limit reached |
DELETE /webhooks/{id}
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Responses
| Status | Description |
|---|---|
204 | Deleted |
404 | Resource not found. |
POST /webhooks/{id}/test
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Responses
| Status | Description |
|---|---|
200 | Queued |
GET /webhooks/{id}/deliveries
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Responses
| Status | Description |
|---|---|
200 | OK |
404 | Resource not found. |
POST /deeplinks
Auth: BearerAuth
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
code | string | — | |
title | string | — | |
targets | object | — | |
active | boolean | — |
Responses
| Status | Description |
|---|---|
201 | Created |
400 | Validation failed. |
GET /deeplinks/{code}
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes |
Responses
| Status | Description |
|---|---|
200 | OK |
404 | Resource not found. |
PATCH /deeplinks/{code}
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes |
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
code | string | — | |
title | string | — | |
targets | object | — | |
active | boolean | — |
Responses
| Status | Description |
|---|---|
200 | OK |
DELETE /deeplinks/{code}
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes |
Responses
| Status | Description |
|---|---|
204 | Deleted |
404 | Resource not found. |
GET /sites
Every site in the workspace the API key belongs to. Not paginated.
Auth: BearerAuth
Responses
| Status | Description |
|---|---|
200 | OK |
401 | Missing, malformed, expired, or revoked token. |
POST /sites
Requires the `links:write` scope.
Auth: BearerAuth
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
pack_key | string | — | Unit template pack to seed labels and destinations from. |
external_id | string | — | |
address | string | — |
Responses
| Status | Description |
|---|---|
201 | Created |
400 | Validation failed. |
401 | Missing, malformed, expired, or revoked token. |
GET /sites/{id}
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Site id (ULID). |
Responses
| Status | Description |
|---|---|
200 | OK |
404 | Resource not found. |
GET /sites/{id}/units
Returns units in fixed unit-number order, including any gaps left by deleted units, so a printed sheet keeps its numbering.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Site id (ULID). |
Responses
| Status | Description |
|---|---|
200 | OK |
404 | Resource not found. |
POST /sites/{id}/units/batch
Creates up to 100 units and a link code for each. Per-unit success and failure are reported individually; the call itself returns 201 even when some units failed. Requires the `links:write` scope.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Site id (ULID). |
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
count | integer | — | |
start_at | integer | — | First unit number. Defaults to the site's next free number. |
label_pattern | string | — | Label template, e.g. "Table {n}". |
zone | string | — | |
destination | object | yes | What every created unit points at. Same shape as a link's content. |
Responses
| Status | Description |
|---|---|
201 | Created (inspect `results` for per-unit outcomes) |
400 | Validation failed. |
404 | Resource not found. |
GET /sites/{id}/leaderboard
Units ranked by scan count, plus the count of units never scanned.
Auth: BearerAuth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Site id (ULID). |
Responses
| Status | Description |
|---|---|
200 | OK |
404 | Resource not found. |
POST /conversions
Closes the loop on a scan. The redirect hands your destination a join key (`qr_click_id`); you hand a conversion back against it, and the scan that started it finally has an outcome. **Idempotency is the contract.** Every platform that sends conversion callbacks retries them - on a timeout, on a 500, on a deploy - and revenue that doubles on a retry is more dangerous than revenue that is missing: a missing number gets investigated, an inflated one gets believed. Send `external_id` (your own id for the conversion) and a replay answers `200` with `duplicate: true`, never an error you would queue and retry forever. Without it, a retry is indistinguishable from a second sale. **Send at least one join key** - `code`, `click_ref`, `session_id` or `visitor`. With none of them the conversion belongs to the workspace and to nothing inside it, which is a number that can be summed and never explained, so it is refused rather than accepted as an orphan. `value_cents` is in MINOR units and the field name says so: a field called `value` taking 12.50 from one integrator and 1250 from the next is a bug nobody can reproduce, and floating-point money is how a revenue report ends up fractionally wrong with nobody able to say why.
Auth: BearerAuth
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
code | string | — | The short code. A code your key does not own is a 404, never someone else's attribution. |
click_ref | string | — | The `qr_click_id` the redirect appended to your destination URL. |
session_id | string | — | |
visitor | string | — | |
kind | string | — | Your name for this kind of conversion, e.g. `purchase`, `booking`. |
value_cents | integer | — | Minor units. 1250 is 12.50. |
currency | string | — | ISO 4217, three letters. |
external_id | string | — | Your id for this conversion. Send it - it is what makes a retry safe. |
occurred_at | string (date-time) | — | When it happened, if not now. ISO 8601. |
metadata | object | — |
Responses
| Status | Description |
|---|---|
200 | Already recorded. The same `external_id` arrived before; this is the answer to a retry and carries the id of the conversion that already exists. |
201 | Recorded |
400 | No join key was sent, or the body failed validation. |
404 | The code is not one this key's workspace owns. |
POST /oauth/token
Client-credentials grant. Accepts `application/x-www-form-urlencoded` (per RFC 6749) or `application/json`; any other content type is 415. `client_credentials` is the only supported grant type. Errors use the OAuth `{error, error_description}` shape, NOT the RFC 9457 problem document the rest of this API returns.
Auth: public
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
grant_type | "client_credentials" | yes | |
client_id | string | yes | |
client_secret | string | yes | |
scope | string | — |
Responses
| Status | Description |
|---|---|
200 | Token issued |
400 | Unsupported grant type |
401 | Invalid client |
415 | Unsupported content type |
The full reference above is part of this page. The interactive tester is a third-party bundle (Scalar), so it loads only when you ask for it. Click any endpoint inside it and use Test Request to send a real call.
Prefer the raw document? /openapi.yaml