API reference

Every endpoint of the 3x REST API v1 (157 routes), generated from the route contracts the API itself is built from. The machine-readable form is the OpenAPI 3.1 document at GET /v1/openapi.json; an interactive reference is served at /docs/api and a markdown rendering of the full schemas at /docs/api.md. Conventions (authentication, errors, pagination, idempotency, rate limits, filters) are described in the other pages of the API section.

System

Operation	Endpoint	Auth
`system.health`	`GET /v1/health`	public
`system.cron`	`GET /v1/cron/{job}`	`CRON_SECRET`

system.health

GET /v1/health – Health check.

Auth: public
Response: 200 JSON (Health)

system.cron

GET /v1/cron/{job} – Run scheduled jobs (Vercel Cron / external scheduler).

job = tick (all due jobs) or a single job name from the job registry. Bearer CRON_SECRET.

Auth: CRON_SECRET
Response: 200 JSON (CronResult)

Path parameters:

Name	Type	Required	Description
`job`	string	yes

Ingest

Operation	Endpoint	Auth
`ingest.collect`	`POST /v1/e`	publishable key (`pk_3x_…`)
`ingest.collectAlias`	`POST /v1/collect`	publishable key (`pk_3x_…`)
`ingest.clientConfig`	`GET /v1/c/{pk}`	publishable key (`pk_3x_…`)
`ingest.script`	`GET /v1/s/{file}`	public
`ingest.sdkPackage`	`GET /v1/sdk/{file}`	public

ingest.collect

POST /v1/e – Collect a tracking batch (browser SDK).

text/plain JSON WireBatch v2 with the publishable key in k. Always answers without body: 204 accepted or dropped (bots, budgets), 400 invalid, 403 origin/key, 413 too large, 429 rate limited.

Auth: publishable key (pk_3x_…)
Response: 204, no body
Body: text/plain (WireBatch)

ingest.collectAlias

POST /v1/collect – Alias of POST /v1/e (same handler; /v1/e is shorter and blocker-neutral).

Auth: publishable key (pk_3x_…)
Response: 204, no body
Body: text/plain (WireBatch)

ingest.clientConfig

GET /v1/c/{pk} – Client configuration for a publishable key.

Auth: publishable key (pk_3x_…)
Response: 200 JSON (ClientConfig)

Path parameters:

Name	Type	Required	Description
`pk`	string	yes

ingest.script

GET /v1/s/{file} – Browser SDK script (x3.js, x3.full.js, x3.{video,sections,forms,identify,consent,bookings}.js, versioned x3@1.2.3.js); ?k=pk_… inlines the client config.

Auth: public
Response: 200 javascript

Path parameters:

Name	Type	Required	Description
`file`	string	yes

Query parameters:

Name	Type	Required	Description
`k`	string	no

ingest.sdkPackage

GET /v1/sdk/{file} – npm tarball of @3x-engine/sdk built with this deployment – npm install <api origin>/v1/sdk/3x-engine-sdk-<version>.tgz (used by the install recipes).

Auth: public
Response: 200 gzip

Path parameters:

Name	Type	Required	Description
`file`	string	yes

Events

Operation	Endpoint	Auth
`ingest.serverEvents`	`POST /v1/projects/{project}/events`	secret key or user session · `events:write` · `Idempotency-Key`
`analytics.liveEvents`	`GET /v1/projects/{project}/events/live`	secret key or user session · `analytics:read`
`events.catalog`	`GET /v1/projects/{project}/event-catalog`	secret key or user session · `analytics:read`
`eventSchemas.upsert`	`PUT /v1/projects/{project}/event-schemas/{name}`	secret key or user session · `config:write`
`eventSchemas.delete`	`DELETE /v1/projects/{project}/event-schemas/{name}`	secret key or user session · `config:write`
`events.validate`	`POST /v1/events/validate`	public

ingest.serverEvents

POST /v1/projects/{project}/events – Send server-side events attached to a browser session.

Auth: secret key or user session · events:write · Idempotency-Key
Response: 202 JSON (ServerEventsResult)
Body: application/json (ServerEvents)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

analytics.liveEvents

GET /v1/projects/{project}/events/live – Events received since a cursor (long-poll up to ?wait=20 seconds, ≤ 200 rows).

Auth: secret key or user session · analytics:read
Response: 200 JSON (LiveEvents)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required
`cursor`	string	no
`wait`	string	no
`names`	string \| string[]	no
`limit`	string	no
`include_test`	"0" \| "1" \| "true" \| "false"	no

events.catalog

GET /v1/projects/{project}/event-catalog – Built-in events, presets, registered and observed custom events.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

eventSchemas.upsert

PUT /v1/projects/{project}/event-schemas/{name} – Register or update a custom event schema.

Auth: secret key or user session · config:write
Response: 200 JSON (EventSchema)
Body: application/json (EventSchemaWrite)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`name`	string	yes

eventSchemas.delete

DELETE /v1/projects/{project}/event-schemas/{name} – Remove a custom event schema (events stay; they become unregistered).

Auth: secret key or user session · config:write
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`name`	string	yes

events.validate

POST /v1/events/validate – Validate a custom event payload against the built-in catalog (and a project's schemas when authorized).

Auth: public
Response: 200 JSON (EventValidateResult)
Body: application/json (EventValidate)

Auth

Operation	Endpoint	Auth
`auth.signup`	`POST /v1/auth/signup`	public
`auth.login`	`POST /v1/auth/login`	public
`auth.logout`	`POST /v1/auth/logout`	dashboard user session
`auth.me`	`GET /v1/auth/me`	dashboard user session
`auth.sudo`	`POST /v1/auth/sudo`	dashboard user session
`auth.magicLink`	`POST /v1/auth/magic-link`	public
`auth.magicLinkVerify`	`POST /v1/auth/magic-link/verify`	public
`auth.password`	`POST /v1/auth/password`	dashboard user session · sudo
`auth.invitationInfo`	`GET /v1/invitations/{token}`	public
`auth.invitationAccept`	`POST /v1/invitations/{token}/accept`	dashboard user session
`oauthGrants.mine`	`GET /v1/auth/oauth-grants`	dashboard user session

auth.signup

POST /v1/auth/signup – Create a user (self-signup when enabled, or with an invitation token).

Auth: public
Response: 201 JSON (SessionToken)
Body: application/json (Signup)

auth.login

POST /v1/auth/login – Log in with e-mail and password; returns a session token (x3s_…).

Auth: public
Response: 200 JSON (SessionToken)
Body: application/json (Login)

auth.logout

POST /v1/auth/logout – Revoke the current session (all=true: every session of the user).

Auth: dashboard user session
Response: 200 JSON (Ok)
Body: application/json

Body fields:

Name	Type	Required	Description
`all`	boolean	no

auth.me

GET /v1/auth/me – Current user, memberships and accessible projects.

Auth: dashboard user session
Response: 200 JSON (Me)

auth.sudo

POST /v1/auth/sudo – Re-authenticate for sensitive actions (15 minutes).

Auth: dashboard user session
Response: 200 JSON
Body: application/json (Sudo)

auth.magicLink

POST /v1/auth/magic-link – Request a magic link (same response whether the account exists).

Auth: public
Response: 202 JSON (Ok)
Body: application/json (MagicLinkRequest)

auth.magicLinkVerify

POST /v1/auth/magic-link/verify – Exchange a magic-link token for a session.

Auth: public
Response: 200 JSON (SessionToken)
Body: application/json (MagicLinkVerify)

auth.password

POST /v1/auth/password – Change the password (sudo).

Auth: dashboard user session · sudo
Response: 200 JSON (Ok)
Body: application/json (PasswordChange)

auth.invitationInfo

GET /v1/invitations/{token} – Invitation details for the accept page.

Auth: public
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`token`	string	yes

auth.invitationAccept

POST /v1/invitations/{token}/accept – Accept an invitation as the logged-in user.

Auth: dashboard user session
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`token`	string	yes

oauthGrants.mine

GET /v1/auth/oauth-grants – Connected apps (OAuth grants) of the logged-in user.

Auth: dashboard user session
Response: 200 JSON

Organizations

Operation	Endpoint	Auth
`orgs.list`	`GET /v1/orgs`	secret key or user session
`orgs.create`	`POST /v1/orgs`	dashboard user session
`orgs.get`	`GET /v1/orgs/{org}`	secret key or user session
`orgs.update`	`PATCH /v1/orgs/{org}`	secret key or user session · `org:admin`
`orgs.delete`	`DELETE /v1/orgs/{org}`	dashboard user session · `org:admin` · sudo
`audit.list`	`GET /v1/orgs/{org}/audit`	secret key or user session · `org:admin`
`oauthGrants.list`	`GET /v1/orgs/{org}/oauth-grants`	secret key or user session · `org:admin`
`oauthGrants.revoke`	`DELETE /v1/orgs/{org}/oauth-grants/{id}`	secret key or user session

orgs.list

GET /v1/orgs – Organizations of the caller.

Auth: secret key or user session
Response: 200 JSON

orgs.create

POST /v1/orgs – Create an organization (the caller becomes owner).

Auth: dashboard user session
Response: 201 JSON (Organization)
Body: application/json (OrganizationCreate)

orgs.get

GET /v1/orgs/{org} – Organization.

Auth: secret key or user session
Response: 200 JSON (Organization)

Path parameters:

Name	Type	Required	Description
`org`	string	yes

orgs.update

PATCH /v1/orgs/{org} – Rename an organization.

Auth: secret key or user session · org:admin
Response: 200 JSON (Organization)
Body: application/json (OrganizationUpdate)

Path parameters:

Name	Type	Required	Description
`org`	string	yes

orgs.delete

DELETE /v1/orgs/{org} – Delete an organization with all projects and data (owner, sudo).

Auth: dashboard user session · org:admin · sudo
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`org`	string	yes

audit.list

GET /v1/orgs/{org}/audit – Audit log (keys, members, projects, config, conversions, connections).

Auth: secret key or user session · org:admin
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`org`	string	yes

Query parameters:

Name	Type	Required
`limit`	string	no
`cursor`	string	no
`project`	string	no
`action`	string	no

oauthGrants.list

GET /v1/orgs/{org}/oauth-grants – OAuth grants into the organization (all members).

Auth: secret key or user session · org:admin
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`org`	string	yes

oauthGrants.revoke

DELETE /v1/orgs/{org}/oauth-grants/{id} – Revoke an OAuth grant (all its tokens).

Auth: secret key or user session
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`org`	string	yes
`id`	string	yes

Members

Operation	Endpoint	Auth
`members.list`	`GET /v1/orgs/{org}/members`	secret key or user session · `org:admin`
`members.update`	`PATCH /v1/orgs/{org}/members/{userId}`	dashboard user session · `org:admin` · sudo
`members.remove`	`DELETE /v1/orgs/{org}/members/{userId}`	dashboard user session · `org:admin` · sudo
`invitations.list`	`GET /v1/orgs/{org}/invitations`	secret key or user session · `org:admin`
`invitations.create`	`POST /v1/orgs/{org}/invitations`	dashboard user session · `org:admin` · sudo
`invitations.revoke`	`DELETE /v1/orgs/{org}/invitations/{id}`	secret key or user session · `org:admin`

members.list

GET /v1/orgs/{org}/members – Members of an organization.

Auth: secret key or user session · org:admin
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`org`	string	yes

members.update

PATCH /v1/orgs/{org}/members/{userId} – Change a member's role or personal-data permission (sudo).

Auth: dashboard user session · org:admin · sudo
Response: 200 JSON (Member)
Body: application/json (MemberUpdate)

Path parameters:

Name	Type	Required	Description
`org`	string	yes
`userId`	string	yes

members.remove

DELETE /v1/orgs/{org}/members/{userId} – Remove a member (sudo; the last owner cannot be removed).

Auth: dashboard user session · org:admin · sudo
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`org`	string	yes
`userId`	string	yes

invitations.list

GET /v1/orgs/{org}/invitations – Open and past invitations.

Auth: secret key or user session · org:admin
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`org`	string	yes

invitations.create

POST /v1/orgs/{org}/invitations – Invite a member (link valid 7 days, single use).

Auth: dashboard user session · org:admin · sudo
Response: 201 JSON (InvitationCreated)
Body: application/json (InvitationCreate)

Path parameters:

Name	Type	Required	Description
`org`	string	yes

invitations.revoke

DELETE /v1/orgs/{org}/invitations/{id} – Revoke an invitation.

Auth: secret key or user session · org:admin
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`org`	string	yes
`id`	string	yes

Keys

Operation	Endpoint	Auth
`keys.list`	`GET /v1/orgs/{org}/keys`	secret key or user session · `org:admin`
`keys.create`	`POST /v1/orgs/{org}/keys`	secret key or user session · `org:admin` · sudo
`keys.roll`	`POST /v1/orgs/{org}/keys/{id}/roll`	secret key or user session · `org:admin` · sudo
`keys.revoke`	`DELETE /v1/orgs/{org}/keys/{id}`	secret key or user session · `org:admin` · sudo
`publishableKeys.list`	`GET /v1/projects/{project}/publishable-keys`	secret key or user session · `analytics:read`
`publishableKeys.create`	`POST /v1/projects/{project}/publishable-keys`	secret key or user session · `project:admin`
`publishableKeys.roll`	`POST /v1/projects/{project}/publishable-keys/{id}/roll`	secret key or user session · `project:admin`
`proxyKeys.list`	`GET /v1/projects/{project}/proxy-keys`	secret key or user session · `project:admin`
`proxyKeys.create`	`POST /v1/projects/{project}/proxy-keys`	secret key or user session · `project:admin`
`proxyKeys.revoke`	`DELETE /v1/projects/{project}/proxy-keys/{id}`	secret key or user session · `project:admin`
`publishableKeys.revoke`	`DELETE /v1/projects/{project}/publishable-keys/{id}`	secret key or user session · `project:admin`

keys.list

GET /v1/orgs/{org}/keys – Secret keys of the organization (never the secret).

Auth: secret key or user session · org:admin
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`org`	string	yes

keys.create

POST /v1/orgs/{org}/keys – Create a secret key – the value is returned once (sudo for users; scopes ≤ caller's).

Auth: secret key or user session · org:admin · sudo
Response: 201 JSON (ApiKeyCreated)
Body: application/json (SecretKeyCreate)

Path parameters:

Name	Type	Required	Description
`org`	string	yes

keys.roll

POST /v1/orgs/{org}/keys/{id}/roll – Roll a secret key: new key now, the old one expires after the overlap (default 7 days).

Auth: secret key or user session · org:admin · sudo
Response: 201 JSON (ApiKeyCreated)
Body: application/json (KeyRoll)

Path parameters:

Name	Type	Required	Description
`org`	string	yes
`id`	string	yes

keys.revoke

DELETE /v1/orgs/{org}/keys/{id} – Revoke a secret key immediately.

Auth: secret key or user session · org:admin · sudo
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`org`	string	yes
`id`	string	yes

publishableKeys.list

GET /v1/projects/{project}/publishable-keys – Publishable keys (pk_3x_…) of the project.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

publishableKeys.create

POST /v1/projects/{project}/publishable-keys – Create a publishable key.

Auth: secret key or user session · project:admin
Response: 201 JSON (ApiKeyCreated)
Body: application/json (PublishableKeyCreate)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

publishableKeys.roll

POST /v1/projects/{project}/publishable-keys/{id}/roll – Roll a publishable key (old key keeps working during the overlap).

Auth: secret key or user session · project:admin
Response: 201 JSON (ApiKeyCreated)
Body: application/json (KeyRoll)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

proxyKeys.list

GET /v1/projects/{project}/proxy-keys – First-party proxy keys of the project (secret keys with exactly ingest:proxy; never the secret).

Auth: secret key or user session · project:admin
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

proxyKeys.create

POST /v1/projects/{project}/proxy-keys – Create a proxy key (scope ingest:proxy, bound to this project) – the value is returned once.

Requires project:admin and the right to grant ingest:proxy (owners/admins; keys and OAuth grants that hold ingest:proxy). Keys created by an OAuth grant or another key are bound to it.

Auth: secret key or user session · project:admin
Response: 201 JSON (ApiKeyCreated)
Body: application/json (ProxyKeyCreate)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

proxyKeys.revoke

DELETE /v1/projects/{project}/proxy-keys/{id} – Revoke a proxy key.

Auth: secret key or user session · project:admin
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

publishableKeys.revoke

DELETE /v1/projects/{project}/publishable-keys/{id} – Revoke a publishable key.

Auth: secret key or user session · project:admin
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

Projects

Operation	Endpoint	Auth
`projects.list`	`GET /v1/projects`	secret key or user session
`projects.create`	`POST /v1/orgs/{org}/projects`	secret key or user session · `project:create`
`projects.get`	`GET /v1/projects/{project}`	secret key or user session
`projects.update`	`PATCH /v1/projects/{project}`	secret key or user session · `project:admin`
`projects.delete`	`DELETE /v1/projects/{project}`	secret key or user session · `org:admin` · sudo
`projects.getConfig`	`GET /v1/projects/{project}/config`	secret key or user session · `analytics:read`
`projects.updateConfig`	`PATCH /v1/projects/{project}/config`	secret key or user session · `project:admin`
`projects.status`	`GET /v1/projects/{project}/status`	secret key or user session · `analytics:read`
`projects.purgeData`	`POST /v1/projects/{project}/purge`	secret key or user session · `project:admin` · sudo

projects.list

GET /v1/projects – Projects the caller can access (all orgs).

Auth: secret key or user session
Response: 200 JSON

Query parameters:

Name	Type	Required	Description
`org`	string	no
`slug`	string	no

projects.create

POST /v1/orgs/{org}/projects – Create a project (returns it with its first publishable key); a project-narrowed key/grant gains access to it.

Auth: secret key or user session · project:create
Response: 201 JSON (ProjectCreated)
Body: application/json (ProjectCreate)

Path parameters:

Name	Type	Required	Description
`org`	string	yes

projects.get

GET /v1/projects/{project} – Project.

Auth: secret key or user session
Response: 200 JSON (Project)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

projects.update

PATCH /v1/projects/{project} – Update project settings (name, time zone, currency, retention, limits …).

Auth: secret key or user session · project:admin
Response: 200 JSON (Project)
Body: application/json (ProjectUpdate)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

projects.delete

DELETE /v1/projects/{project} – Delete a project and all its data (sudo).

Auth: secret key or user session · org:admin · sudo
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

projects.getConfig

GET /v1/projects/{project}/config – Tracking configuration (domains, origins, page groups, personal pages, consent, presets …).

Auth: secret key or user session · analytics:read
Response: 200 JSON (ProjectTrackingConfigResponse)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

projects.updateConfig

PATCH /v1/projects/{project}/config – Update tracking configuration (top-level keys replace stored values; bumps configRev).

Auth: secret key or user session · project:admin
Response: 200 JSON (ProjectTrackingConfigResponse)
Body: application/json (TrackingConfigPatch)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

projects.status

GET /v1/projects/{project}/status – Tracking status: database, storage, cleanup, rescoring progress, budgets, proxy warning, last event.

Auth: secret key or user session · analytics:read
Response: 200 JSON (ProjectStatus)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

projects.purgeData

POST /v1/projects/{project}/purge – Delete tracking data in a date range or all of it (sudo).

Auth: secret key or user session · project:admin · sudo
Response: 200 JSON
Body: application/json

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Body fields:

Name	Type	Required
`scope`	"all" \| "range" \| "test"	yes
`from`	string	no
`to`	string	no

Analytics

Operation	Endpoint	Auth
`analytics.overview`	`GET /v1/projects/{project}/analytics/overview`	secret key or user session · `analytics:read`
`analytics.timeseries`	`GET /v1/projects/{project}/analytics/timeseries`	secret key or user session · `analytics:read`
`analytics.funnel`	`GET /v1/projects/{project}/analytics/funnel`	secret key or user session · `analytics:read`
`analytics.breakdown`	`GET /v1/projects/{project}/analytics/breakdown`	secret key or user session · `analytics:read`
`analytics.relevanceRanking`	`GET /v1/projects/{project}/analytics/relevance-ranking`	secret key or user session · `analytics:read`
`analytics.pages`	`GET /v1/projects/{project}/analytics/pages`	secret key or user session · `analytics:read`
`analytics.scroll`	`GET /v1/projects/{project}/analytics/scroll`	secret key or user session · `analytics:read`
`analytics.sections`	`GET /v1/projects/{project}/analytics/sections`	secret key or user session · `analytics:read`
`analytics.engagement`	`GET /v1/projects/{project}/analytics/engagement`	secret key or user session · `analytics:read`
`analytics.clicks`	`GET /v1/projects/{project}/analytics/clicks`	secret key or user session · `analytics:read`
`analytics.videos`	`GET /v1/projects/{project}/analytics/videos`	secret key or user session · `analytics:read`
`analytics.videoRetention`	`GET /v1/projects/{project}/analytics/videos/{video}/retention`	secret key or user session · `analytics:read`
`analytics.answers`	`GET /v1/projects/{project}/analytics/answers`	secret key or user session · `analytics:read`
`analytics.flow`	`GET /v1/projects/{project}/analytics/flow`	secret key or user session · `analytics:read`
`analytics.goals`	`GET /v1/projects/{project}/analytics/goals`	secret key or user session · `analytics:read`
`analytics.filterOptions`	`GET /v1/projects/{project}/analytics/filter-options`	secret key or user session · `analytics:read`
`analytics.events`	`GET /v1/projects/{project}/analytics/events`	secret key or user session · `analytics:read`
`sql.query`	`POST /v1/projects/{project}/sql`	secret key or user session · `analytics:read`
`schema.get`	`GET /v1/projects/{project}/schema`	secret key or user session · `analytics:read`

analytics.overview

GET /v1/projects/{project}/analytics/overview – KPIs, extras, time series, default funnel, previous-period comparison.

Auth: secret key or user session · analytics:read
Response: 200 JSON (Overview)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`bucket`	"hour" \| "day" \| "week"	no
`compare`	"0" \| "1" \| "true" \| "false"	no

analytics.timeseries

GET /v1/projects/{project}/analytics/timeseries – Zero-filled series of sessions, visitors, pageviews, conversions.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`bucket`	"hour" \| "day" \| "week"	no

analytics.funnel

GET /v1/projects/{project}/analytics/funnel – Funnel steps (default funnel or ?funnel=<key>).

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`funnel`	string	no

analytics.breakdown

GET /v1/projects/{project}/analytics/breakdown – Full session aggregate per value of a dimension.

Auth: secret key or user session · analytics:read
Response: 200 JSON (Breakdown)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`dimension`	"channel" \| "utm_source" \| "utm_medium" \| "utm_campaign" \| "utm_content" \| "utm_term" \| "utm_id" \| "ref_host" \| "entry_page" \| "entry_group" \| "variant" \| "device" \| "browser" \| "os" \| "country" \| "lang" \| "exit_page" \| "exit_group" \| "entry_host" \| "screen" \| "stitch" \| "attr_from" \| "click_id" \| "converted" \| "quiz_answers" \| "consent" \| "relevance_tier" \| "goal" \| "ad_platform" \| "ad_campaign" \| "ad_adset" \| "ad" \| "day" \| "week" \| "month" \| "hour_of_day" \| "weekday"	yes
`sort`	string	no
`dir`	"asc" \| "desc"	no
`limit`	string	no
`min_sessions`	string	no

analytics.relevanceRanking

GET /v1/projects/{project}/analytics/relevance-ranking – Rank values of a dimension by relevance (default utm_campaign).

Auth: secret key or user session · analytics:read
Response: 200 JSON (RelevanceRanking)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`dimension`	"channel" \| "utm_source" \| "utm_medium" \| "utm_campaign" \| "utm_content" \| "utm_term" \| "utm_id" \| "ref_host" \| "entry_page" \| "entry_group" \| "variant" \| "device" \| "browser" \| "os" \| "country" \| "lang"	no
`sort`	"avg" \| "hot" \| "hot_rate" \| "engaged_rate" \| "sessions"	no
`min_sessions`	string	no
`limit`	string	no

analytics.pages

GET /v1/projects/{project}/analytics/pages – Pages: pageviews, sessions, entries, exits, engagement, scroll, fold-only, clicks, video.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`limit`	string	no

analytics.scroll

GET /v1/projects/{project}/analytics/scroll – Scroll curve, fold-only rate, fold share, milestones (restored scroll positions excluded).

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match

analytics.sections

GET /v1/projects/{project}/analytics/sections – Section reach per page.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`limit`	string	no

analytics.engagement

GET /v1/projects/{project}/analytics/engagement – Engaged-time distribution per pageview or session.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`level`	"pageview" \| "session"	no

analytics.clicks

GET /v1/projects/{project}/analytics/clicks – Top clicks by label/kind/tag/href/section.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`limit`	string	no

analytics.videos

GET /v1/projects/{project}/analytics/videos – Video plays, start rate, watched time, coverage, completion, retention.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match

analytics.videoRetention

GET /v1/projects/{project}/analytics/videos/{video}/retention – Downsampled retention curve of one video, overall and per format.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`video`	string	yes

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`step`	string	no

analytics.answers

GET /v1/projects/{project}/analytics/answers – Questionnaire (quiz) funnel and option distribution per question.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`questionnaire`	string	no

analytics.flow

GET /v1/projects/{project}/analytics/flow – Entry pages, exit pages and page transitions.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`limit`	string	no

analytics.goals

GET /v1/projects/{project}/analytics/goals – Goal completions (sessions, rate, value).

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match

analytics.filterOptions

GET /v1/projects/{project}/analytics/filter-options – Top values per filter dimension for the date range.

Auth: secret key or user session · analytics:read
Response: 200 JSON (FilterOptions)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match

analytics.events

GET /v1/projects/{project}/analytics/events – Raw events with session context (names, prop containment, prop text search).

Auth: secret key or user session · analytics:read
Response: 200 JSON (EventsQueryResult)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`names`	string \| string[]	no
`props`	string	no
`prop_key`	string	no
`prop_text`	string	no
`session_id`	string	no
`order`	"asc" \| "desc"	no
`limit`	string	no

sql.query

POST /v1/projects/{project}/sql – Read-only SQL over the project's analytics tables (one SELECT/WITH, row-level isolated).

Auth: secret key or user session · analytics:read
Response: 200 JSON (SqlResult)
Body: application/json

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Body fields:

Name	Type	Required	Description
`query`	string	yes
`maxRows`	int	no

schema.get

GET /v1/projects/{project}/schema – Tables and columns available to SQL, filter semantics, conventions.

Auth: secret key or user session · analytics:read
Response: 200 JSON (SchemaDoc)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Sessions

Operation	Endpoint	Auth
`sessions.list`	`GET /v1/projects/{project}/sessions`	secret key or user session · `analytics:read`
`sessions.get`	`GET /v1/projects/{project}/sessions/{sessionId}`	secret key or user session · `analytics:read`

sessions.list

GET /v1/projects/{project}/sessions – Sessions explorer (sortable, paginated).

Auth: secret key or user session · analytics:read
Response: 200 JSON (SessionList)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`sort`	"started_at" \| "relevance" \| "engaged" \| "pages" \| "clicks" \| "scroll" \| "video"	no
`dir`	"asc" \| "desc"	no
`limit`	string	no
`offset`	string	no

sessions.get

GET /v1/projects/{project}/sessions/{sessionId} – One session: attribution, relevance breakdown, pageviews with merged timeline, conversions, leads.

Auth: secret key or user session · analytics:read
Response: 200 JSON (SessionDetail)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`sessionId`	string	yes

Query parameters:

Name	Type	Required	Description
`sections`	"0" \| "1" \| "true" \| "false"	no
`locale`	"en" \| "de"	no

Goals & funnels

Operation	Endpoint	Auth
`goals.list`	`GET /v1/projects/{project}/goals`	secret key or user session · `analytics:read`
`goals.create`	`POST /v1/projects/{project}/goals`	secret key or user session · `config:write`
`goals.update`	`PATCH /v1/projects/{project}/goals/{key}`	secret key or user session · `config:write`
`goals.delete`	`DELETE /v1/projects/{project}/goals/{key}`	secret key or user session · `config:write`
`funnels.list`	`GET /v1/projects/{project}/funnels`	secret key or user session · `analytics:read`
`funnels.create`	`POST /v1/projects/{project}/funnels`	secret key or user session · `config:write`
`funnels.update`	`PATCH /v1/projects/{project}/funnels/{key}`	secret key or user session · `config:write`
`funnels.delete`	`DELETE /v1/projects/{project}/funnels/{key}`	secret key or user session · `config:write`
`questionnaires.list`	`GET /v1/projects/{project}/questionnaires`	secret key or user session · `analytics:read`
`questionnaires.upsert`	`PUT /v1/projects/{project}/questionnaires/{id}`	secret key or user session · `config:write`
`questionnaires.delete`	`DELETE /v1/projects/{project}/questionnaires/{id}`	secret key or user session · `config:write`

goals.list

GET /v1/projects/{project}/goals – Goals.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`archived`	"0" \| "1" \| "true" \| "false"	no

goals.create

POST /v1/projects/{project}/goals – Create a goal (bumps goalsVersion → sessions are recomputed in the background).

Auth: secret key or user session · config:write
Response: 201 JSON (Goal)
Body: application/json (GoalWrite)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

goals.update

PATCH /v1/projects/{project}/goals/{key} – Update a goal.

Auth: secret key or user session · config:write
Response: 200 JSON (Goal)
Body: application/json

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`key`	string	yes

Body fields:

Name	Type	Required
`name`	string	no
`match`	object	no
`isConversion`	boolean	no
`value`	number \| null	no
`sort`	int	no
`archived`	boolean	no

goals.delete

DELETE /v1/projects/{project}/goals/{key} – Delete a goal.

Auth: secret key or user session · config:write
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`key`	string	yes

funnels.list

GET /v1/projects/{project}/funnels – Funnel definitions.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

funnels.create

POST /v1/projects/{project}/funnels – Create a funnel.

Auth: secret key or user session · config:write
Response: 201 JSON (Funnel)
Body: application/json (FunnelWrite)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

funnels.update

PATCH /v1/projects/{project}/funnels/{key} – Update a funnel.

Auth: secret key or user session · config:write
Response: 200 JSON (Funnel)
Body: application/json

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`key`	string	yes

Body fields:

Name	Type	Required
`name`	string	no
`mode`	"independent" \| "sequential"	no
`steps`	object[]	no
`isDefault`	boolean	no
`sort`	int	no

funnels.delete

DELETE /v1/projects/{project}/funnels/{key} – Delete a funnel.

Auth: secret key or user session · config:write
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`key`	string	yes

questionnaires.list

GET /v1/projects/{project}/questionnaires – Questionnaire (quiz) definitions.

Auth: secret key or user session · analytics:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

questionnaires.upsert

PUT /v1/projects/{project}/questionnaires/{id} – Create or replace a questionnaire (validates quiz_answer events, labels answer analytics).

Auth: secret key or user session · config:write
Response: 200 JSON (Questionnaire)
Body: application/json

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

Body fields:

Name	Type	Required	Description
`label`	string \| object	yes
`questions`	object[]	yes

questionnaires.delete

DELETE /v1/projects/{project}/questionnaires/{id} – Delete a questionnaire.

Auth: secret key or user session · config:write
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

Relevance

Operation	Endpoint	Auth
`relevance.get`	`GET /v1/projects/{project}/relevance`	secret key or user session · `analytics:read`
`relevance.update`	`PUT /v1/projects/{project}/relevance`	secret key or user session · `config:write`
`relevance.preview`	`POST /v1/projects/{project}/relevance/preview`	secret key or user session · `analytics:read`
`relevance.rescore`	`POST /v1/projects/{project}/relevance/rescore`	secret key or user session · `config:write`

relevance.get

GET /v1/projects/{project}/relevance – Active relevance model, version history and rescoring progress.

Auth: secret key or user session · analytics:read
Response: 200 JSON (RelevanceState)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

relevance.update

PUT /v1/projects/{project}/relevance – Save a new relevance model version (all sessions are rescored retroactively).

Auth: secret key or user session · config:write
Response: 200 JSON (RelevanceState)
Body: application/json

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Body fields:

Name	Type	Required	Description
`config`	object	yes
`note`	string	no

relevance.preview

POST /v1/projects/{project}/relevance/preview – Score distribution of a proposed model on recent sessions (nothing is stored).

Auth: secret key or user session · analytics:read
Response: 200 JSON (RelevancePreview)
Body: application/json

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Body fields:

Name	Type	Required	Description
`config`	object	yes
`sample`	int	no

relevance.rescore

POST /v1/projects/{project}/relevance/rescore – Run a rescoring chunk now (normally done by the scheduler).

Auth: secret key or user session · config:write
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Conversions

Operation	Endpoint	Auth
`conversions.list`	`GET /v1/projects/{project}/conversions`	secret key or user session · `conversions:read`
`conversions.create`	`POST /v1/projects/{project}/conversions`	secret key or user session · `conversions:write` · `Idempotency-Key`
`conversions.get`	`GET /v1/projects/{project}/conversions/{id}`	secret key or user session · `conversions:read`
`conversions.retry`	`POST /v1/projects/{project}/conversions/{id}/retry`	secret key or user session · `conversions:write`
`conversions.updateStatus`	`PATCH /v1/projects/{project}/conversions/{id}/status`	secret key or user session · `conversions:write`
`conversions.beacon`	`POST /v1/cb`	publishable key (`pk_3x_…`)
`conversions.googleAdsFeed`	`GET /v1/projects/{project}/feeds/google-ads.csv`	public
`conversionDefinitions.list`	`GET /v1/projects/{project}/conversion-definitions`	secret key or user session · `conversions:read`
`conversionDefinitions.upsert`	`PUT /v1/projects/{project}/conversion-definitions/{key}`	secret key or user session · `conversions:write` + `config:write`
`conversionDefinitions.delete`	`DELETE /v1/projects/{project}/conversion-definitions/{key}`	secret key or user session · `conversions:write` + `config:write`
`destinations.list`	`GET /v1/projects/{project}/destinations`	secret key or user session · `conversions:read`
`destinations.update`	`PUT /v1/projects/{project}/destinations/{provider}`	secret key or user session · `project:admin` · sudo
`destinations.test`	`POST /v1/projects/{project}/destinations/{provider}/test`	secret key or user session · `project:admin`

conversions.list

GET /v1/projects/{project}/conversions – Conversions with per-provider upload status (never hashes, IP, user agent).

Auth: secret key or user session · conversions:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required
`status`	"held" \| "pending" \| "uploaded" \| "skipped"	no
`source`	"quiz" \| "booking" \| "whatsapp_manual" \| "manual" \| "event" \| "goal" \| "lead" \| "api"	no
`definition`	string	no
`session_id`	string	no
`provider`	"meta" \| "linkedin" \| "google_ads" \| "tiktok"	no
`provider_status`	"pending" \| "uploaded" \| "feed" \| "failed" \| "skipped" \| "not_configured" \| "dry_run" \| "error"	no
`days`	string	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`limit`	string	no
`cursor`	string	no

conversions.create

POST /v1/projects/{project}/conversions – Record a conversion and upload it to the configured destinations.

sessionId (from the browser's getIds()) or match {at, windowMinutes, …} to find the session; contact data is hashed on receipt. Ambiguous matches return ≤ 10 candidates. Idempotent via eventId and the Idempotency-Key header.

Auth: secret key or user session · conversions:write · Idempotency-Key
Response: 200 JSON (ConversionCreateResult)
Body: application/json (ConversionCreate)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

conversions.get

GET /v1/projects/{project}/conversions/{id} – One conversion.

Auth: secret key or user session · conversions:read
Response: 200 JSON (Conversion)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

conversions.retry

POST /v1/projects/{project}/conversions/{id}/retry – Retry uploads (default: every provider not uploaded/feed); force resets attempts.

Auth: secret key or user session · conversions:write
Response: 200 JSON (Conversion)
Body: application/json (ConversionRetry)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

conversions.updateStatus

PATCH /v1/projects/{project}/conversions/{id}/status – Manual bookkeeping of conversion/provider status.

Auth: secret key or user session · conversions:write
Response: 200 JSON (Conversion)
Body: application/json (ConversionStatusUpdate)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

conversions.beacon

POST /v1/cb – Browser conversion beacon (booking parity): allowed origins only, ≤ 4 KB, 4/min/IP, one per session and definition.

Auth: publishable key (pk_3x_…)
Response: 202, no body
Body: text/plain

Body fields:

Name	Type	Required
`k`	string	yes
`definition`	string	yes
`eventId`	string	yes
`sid`	string \| null	yes
`pv`	string \| null	yes
`url`	string \| null	yes
`attr`	object \| null	yes
`test`	boolean	yes
`em`	string	no
`emg`	string	no
`fn`	string	no
`ln`	string	no
`ph`	string	no
`fbp`	string	no
`fbc`	string	no
`ttp`	string	no

conversions.googleAdsFeed

GET /v1/projects/{project}/feeds/google-ads.csv – Google Ads scheduled-upload CSV (HTTP Basic with the feed credentials; last 60 days).

Auth: public
Response: 200 csv

Path parameters:

Name	Type	Required	Description
`project`	string	yes

Query parameters:

Name	Type	Required	Description
`source`	string	no
`definition`	string	no

conversionDefinitions.list

GET /v1/projects/{project}/conversion-definitions – Conversion definitions (trigger → provider events).

Auth: secret key or user session · conversions:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

conversionDefinitions.upsert

PUT /v1/projects/{project}/conversion-definitions/{key} – Create or replace a conversion definition.

Auth: secret key or user session · conversions:write + config:write
Response: 200 JSON (ConversionDefinition)
Body: application/json (ConversionDefinitionWrite)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`key`	string	yes

conversionDefinitions.delete

DELETE /v1/projects/{project}/conversion-definitions/{key} – Delete a conversion definition (existing conversions keep it as text).

Auth: secret key or user session · conversions:write + config:write
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`key`	string	yes

destinations.list

GET /v1/projects/{project}/destinations – Conversion destinations (Meta, LinkedIn, Google Ads, TikTok) – secrets are never returned.

Auth: secret key or user session · conversions:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

destinations.update

PUT /v1/projects/{project}/destinations/{provider} – Configure a destination (settings, encrypted secrets, transport direct/composio/feed, mode).

Auth: secret key or user session · project:admin · sudo
Response: 200 JSON (Destination)
Body: application/json (DestinationWrite)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`provider`	"meta" \| "linkedin" \| "google_ads" \| "tiktok"	yes

destinations.test

POST /v1/projects/{project}/destinations/{provider}/test – Send a test event (Meta test_event_code, Google validateOnly, LinkedIn/TikTok validation).

Auth: secret key or user session · project:admin
Response: 200 JSON (DestinationTestResult)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`provider`	"meta" \| "linkedin" \| "google_ads" \| "tiktok"	yes

Leads

Operation	Endpoint	Auth
`leads.list`	`GET /v1/projects/{project}/leads`	secret key or user session · `leads:read`
`leads.get`	`GET /v1/projects/{project}/leads/{id}`	secret key or user session · `leads:read`
`leads.create`	`POST /v1/projects/{project}/leads`	secret key or user session · `leads:write` · `Idempotency-Key`
`leads.delete`	`DELETE /v1/projects/{project}/leads/{id}`	secret key or user session · `leads:write`
`leads.export`	`GET /v1/projects/{project}/leads.csv`	secret key or user session · `leads:read`

leads.list

GET /v1/projects/{project}/leads – Leads (personal data).

Auth: secret key or user session · leads:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required
`days`	string	no
`form`	string	no
`source`	"identify" \| "api" \| "import"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`include_spam`	"0" \| "1" \| "true" \| "false"	no
`limit`	string	no
`cursor`	string	no

leads.get

GET /v1/projects/{project}/leads/{id} – One lead.

Auth: secret key or user session · leads:read
Response: 200 JSON (Lead)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

leads.create

POST /v1/projects/{project}/leads – Record a lead from the site's server (optionally with a conversion).

Auth: secret key or user session · leads:write · Idempotency-Key
Response: 201 JSON
Body: application/json (LeadCreate)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

leads.delete

DELETE /v1/projects/{project}/leads/{id} – Erase a lead (GDPR); linked conversions lose their hashed identifiers.

Auth: secret key or user session · leads:write
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

leads.export

GET /v1/projects/{project}/leads.csv – CSV export of leads.

Auth: secret key or user session · leads:read
Response: 200 csv

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required
`days`	string	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`include_spam`	"0" \| "1" \| "true" \| "false"	no

Operation	Endpoint	Auth
`ads.connections.list`	`GET /v1/projects/{project}/ad-connections`	secret key or user session · `ads:read`
`ads.connections.create`	`POST /v1/projects/{project}/ad-connections`	dashboard user session · `ads:write` · sudo
`ads.connections.complete`	`POST /v1/projects/{project}/ad-connections/{id}/complete`	dashboard user session · `ads:write`
`ads.connections.discover`	`GET /v1/projects/{project}/ad-connections/{id}/accounts`	secret key or user session · `ads:write`
`ads.connections.delete`	`DELETE /v1/projects/{project}/ad-connections/{id}`	secret key or user session · `ads:write` · sudo
`ads.accounts.list`	`GET /v1/projects/{project}/ad-accounts`	secret key or user session · `ads:read`
`ads.accounts.select`	`PUT /v1/projects/{project}/ad-accounts`	secret key or user session · `ads:write`
`ads.sync.run`	`POST /v1/projects/{project}/ads/sync`	secret key or user session · `ads:write`
`ads.sync.runs`	`GET /v1/projects/{project}/ads/sync-runs`	secret key or user session · `ads:read`
`ads.report`	`GET /v1/projects/{project}/ads/report`	secret key or user session · `ads:read`
`ads.timeseries`	`GET /v1/projects/{project}/ads/timeseries`	secret key or user session · `ads:read`
`ads.unmatched`	`GET /v1/projects/{project}/ads/unmatched`	secret key or user session · `ads:read`
`ads.entities`	`GET /v1/projects/{project}/ads/entities`	secret key or user session · `ads:read`
`ads.mappingRules.list`	`GET /v1/projects/{project}/ads/mapping-rules`	secret key or user session · `ads:read`
`ads.mappingRules.create`	`POST /v1/projects/{project}/ads/mapping-rules`	secret key or user session · `ads:write`
`ads.mappingRules.delete`	`DELETE /v1/projects/{project}/ads/mapping-rules/{id}`	secret key or user session · `ads:write`
`ads.utmTemplates`	`GET /v1/projects/{project}/ads/utm-templates`	secret key or user session · `ads:read`
`ads.orgConnections.list`	`GET /v1/orgs/{org}/ad-connections`	secret key or user session · `org:admin`
`ads.orgConnections.create`	`POST /v1/orgs/{org}/ad-connections`	dashboard user session · `org:admin` · sudo
`ads.orgConnections.complete`	`POST /v1/orgs/{org}/ad-connections/{id}/complete`	dashboard user session · `org:admin`
`ads.orgConnections.discover`	`GET /v1/orgs/{org}/ad-connections/{id}/accounts`	secret key or user session · `org:admin`
`ads.orgConnections.delete`	`DELETE /v1/orgs/{org}/ad-connections/{id}`	dashboard user session · `org:admin` · sudo
`ads.webhook`	`POST /v1/webhooks/composio`	webhook signature

ads.connections.list

GET /v1/projects/{project}/ad-connections – Ad-platform connections of the project.

Auth: secret key or user session · ads:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

ads.connections.create

POST /v1/projects/{project}/ad-connections – Start connecting an ad platform (returns the hosted OAuth URL, valid 10 minutes).

Auth: dashboard user session · ads:write · sudo
Response: 201 JSON (AdConnectionStarted)
Body: application/json (AdConnectionCreate)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

ads.connections.complete

POST /v1/projects/{project}/ad-connections/{id}/complete – Finish the OAuth callback (nonce + connected account verified) and discover ad accounts.

Auth: dashboard user session · ads:write
Response: 200 JSON
Body: application/json (AdConnectionComplete)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

ads.connections.discover

GET /v1/projects/{project}/ad-connections/{id}/accounts – Ad accounts reachable through a connection.

Auth: secret key or user session · ads:write
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

ads.connections.delete

DELETE /v1/projects/{project}/ad-connections/{id} – Disconnect (revoke at Composio); cost data is kept unless purge=true.

Auth: secret key or user session · ads:write · sudo
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

Query parameters:

Name	Type	Required	Description
`purge`	"true" \| "false"	no

ads.accounts.list

GET /v1/projects/{project}/ad-accounts – Ad accounts assigned to the project.

Auth: secret key or user session · ads:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

ads.accounts.select

PUT /v1/projects/{project}/ad-accounts – Assign ad accounts of a connection to the project (starts a 90-day backfill).

Auth: secret key or user session · ads:write
Response: 200 JSON
Body: application/json (AdAccountsSelect)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

ads.sync.run

POST /v1/projects/{project}/ads/sync – Queue a sync (entities, metrics, Google click_view, backfill, session matching).

Auth: secret key or user session · ads:write
Response: 202 JSON
Body: application/json (AdSyncRequest)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

ads.sync.runs

GET /v1/projects/{project}/ads/sync-runs – Recent sync runs and their status.

Auth: secret key or user session · ads:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`limit`	string	no
`platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no

ads.report

GET /v1/projects/{project}/ads/report – Spend × sessions × conversions: CPC, cost per session, cost per relevant session, CPL, ROAS.

Auth: secret key or user session · ads:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`level`	"platform" \| "campaign" \| "adset" \| "ad"	no
`sort`	string	no
`dir`	"asc" \| "desc"	no
`limit`	string	no
`relevant_min`	string	no

ads.timeseries

GET /v1/projects/{project}/ads/timeseries – Daily/weekly spend next to sessions, relevant sessions and conversions.

Auth: secret key or user session · ads:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`bucket`	"day" \| "week"	no

ads.unmatched

GET /v1/projects/{project}/ads/unmatched – Paid sessions whose UTMs could not be tied to an ad entity (for manual mapping).

Auth: secret key or user session · ads:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`from`	string	no	Start day YYYY-MM-DD (project time zone, inclusive). Wins over preset.
`to`	string	no	End day YYYY-MM-DD (inclusive). Default today.
`preset`	"today" \| "yesterday" \| "7d" \| "14d" \| "30d" \| "90d" \| "365d" \| "this_month" \| "last_month" \| "all"	no	Date range when from/to are absent. Default 30d; all = last 731 days.
`page`	string	no	Canonical page path, e.g. /pricing
`page_group`	string	no	Page group key from the project config
`page_mode`	"any" \| "entry" \| "exit"	no	Session metrics: any = a pageview on page/page_group (default), entry = entered there, exit = left there
`channel`	"google_ads" \| "google_organic" \| "bing" \| "search_other" \| "meta" \| "linkedin" \| "tiktok" \| "social_other" \| "email" \| "ai_assistant" \| "referral" \| "direct" \| "other"	no
`utm_source`	string	no
`utm_medium`	string	no
`utm_campaign`	string	no
`utm_content`	string	no
`utm_term`	string	no
`utm_id`	string	no
`ref_host`	string	no	Entry referrer host, e.g. www.google.com
`variant`	string	no	Page variant of the entry pageview
`device`	"mobile" \| "tablet" \| "desktop" \| "unknown"	no
`browser`	"chrome" \| "safari" \| "firefox" \| "edge" \| "samsung" \| "opera" \| "other"	no
`os`	"windows" \| "macos" \| "ios" \| "android" \| "linux" \| "chromeos" \| "other"	no
`country`	string	no	ISO country code, uppercase
`lang`	string	no
`screen`	"xs" \| "sm" \| "md" \| "lg" \| "xl"	no
`converted`	"0" \| "1" \| "true" \| "false"	no
`has`	string \| string[]	no
`goal`	string \| string[]	no
`event`	string \| string[]	no
`click_id`	"any" \| "none" \| "gclid" \| "gbraid" \| "wbraid" \| "fbclid" \| "li_fat_id" \| "ttclid" \| "msclkid"	no	any/none or a specific click id present on the session
`traffic`	"paid" \| "organic"	no	paid = an ad click id or a paid utm_medium (cpc, paid, …) on the session; organic = neither
`stitch`	"new" \| "memory" \| "storage" \| "hash"	no
`consent`	"0" \| "1" \| "true" \| "false"	no
`include_test`	"0" \| "1" \| "true" \| "false"	no
`min_relevance`	string	no
`max_relevance`	string	no
`relevance_tier`	string	no	Tier key, e.g. hot
`ad_platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`ad_account_id`	string	no
`ad_campaign_id`	string	no
`ad_adset_id`	string	no
`ad_id`	string	no
`ad_match`	"matched" \| "unmatched"	no	Sessions with/without an ad-entity match
`limit`	string	no

ads.entities

GET /v1/projects/{project}/ads/entities – Synced campaigns, ad sets and ads (search by name/id).

Auth: secret key or user session · ads:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required
`platform`	"google_ads" \| "meta_ads" \| "linkedin_ads" \| "tiktok_ads"	no
`level`	"campaign" \| "adset" \| "ad"	no
`q`	string	no
`limit`	string	no

ads.mappingRules.list

GET /v1/projects/{project}/ads/mapping-rules – Manual UTM → ad entity mapping rules.

Auth: secret key or user session · ads:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

ads.mappingRules.create

POST /v1/projects/{project}/ads/mapping-rules – Create a mapping rule (sessions are re-matched in the background).

Auth: secret key or user session · ads:write
Response: 201 JSON (AdMappingRule)
Body: application/json (AdMappingRuleWrite)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

ads.mappingRules.delete

DELETE /v1/projects/{project}/ads/mapping-rules/{id} – Delete a mapping rule.

Auth: secret key or user session · ads:write
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`id`	string	yes

ads.utmTemplates

GET /v1/projects/{project}/ads/utm-templates – Recommended ID-based UTM templates per platform.

Auth: secret key or user session · ads:read
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

ads.orgConnections.list

GET /v1/orgs/{org}/ad-connections – Org-level ad-platform connections (usable by every project of the organization).

Auth: secret key or user session · org:admin
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`org`	string	yes

ads.orgConnections.create

POST /v1/orgs/{org}/ad-connections – Start an org-level ad-platform connection (returns the hosted OAuth URL, valid 10 minutes).

Auth: dashboard user session · org:admin · sudo
Response: 201 JSON (AdConnectionStarted)
Body: application/json (AdConnectionCreate)

Path parameters:

Name	Type	Required	Description
`org`	string	yes

ads.orgConnections.complete

POST /v1/orgs/{org}/ad-connections/{id}/complete – Finish the OAuth callback of an org-level connection and discover ad accounts.

Auth: dashboard user session · org:admin
Response: 200 JSON
Body: application/json (AdConnectionComplete)

Path parameters:

Name	Type	Required	Description
`org`	string	yes
`id`	string	yes

ads.orgConnections.discover

GET /v1/orgs/{org}/ad-connections/{id}/accounts – Ad accounts reachable through an org-level connection.

Auth: secret key or user session · org:admin
Response: 200 JSON

Path parameters:

Name	Type	Required	Description
`org`	string	yes
`id`	string	yes

ads.orgConnections.delete

DELETE /v1/orgs/{org}/ad-connections/{id} – Disconnect an org-level connection (its accounts are removed from every project); cost data is kept unless purge=true.

Auth: dashboard user session · org:admin · sudo
Response: 204, no body

Path parameters:

Name	Type	Required	Description
`org`	string	yes
`id`	string	yes

Query parameters:

Name	Type	Required	Description
`purge`	"true" \| "false"	no

ads.webhook

POST /v1/webhooks/composio – Composio webhook (connected account expired/activated); signature verified.

Auth: webhook signature
Response: 204, no body

Setup

Operation	Endpoint	Auth
`setup.frameworks`	`GET /v1/setup/frameworks`	public
`setup.detect`	`POST /v1/setup/detect`	public
`setup.instructions`	`GET /v1/setup/instructions`	public
`setup.snippet`	`GET /v1/projects/{project}/setup/snippet`	secret key or user session · `project:admin`
`setup.verify`	`POST /v1/projects/{project}/setup/verify`	secret key or user session · `project:admin`
`setup.status`	`GET /v1/projects/{project}/setup/status`	secret key or user session · `analytics:read`
`setup.progress`	`PATCH /v1/projects/{project}/setup`	secret key or user session · `analytics:read`
`setup.installation`	`GET /v1/projects/{project}/setup/installation`	secret key or user session · `analytics:read`
`setup.prompts`	`GET /v1/projects/{project}/setup/prompts`	secret key or user session · `analytics:read`
`setup.prompt`	`GET /v1/projects/{project}/setup/prompts/{kind}`	secret key or user session · `analytics:read`
`setup.testConversion`	`POST /v1/projects/{project}/setup/test-conversion`	secret key or user session · `project:admin`
`setup.mcpActivity`	`GET /v1/projects/{project}/setup/mcp-activity`	secret key or user session · `analytics:read`
`setup.detectStack`	`POST /v1/projects/{project}/setup/detect-stack`	secret key or user session · `analytics:read`

setup.frameworks

GET /v1/setup/frameworks – Supported frameworks and proxy options.

Auth: public
Response: 200 JSON

setup.detect

POST /v1/setup/detect – Detect framework/router/proxy option from package.json dependencies and a file list.

Auth: public
Response: 200 JSON (DetectStackResult)
Body: application/json (DetectStackInput)

setup.instructions

GET /v1/setup/instructions – Ordered install steps (files, code, env vars, commands) for a framework.

Auth: public
Response: 200 JSON (SetupInstructions)

Query parameters:

Name	Type	Required
`framework`	"next-app" \| "next-pages" \| "react-vite" \| "astro" \| "wordpress" \| "webflow-html" \| "shopify" \| "other"	yes
`proxy`	"route-handler" \| "cloudflare-worker" \| "nginx" \| "netlify" \| "wordpress" \| "cname" \| "none"	no
`consent`	"none" \| "custom" \| "cookiebot" \| "usercentrics" \| "complianz" \| "borlabs" \| "google_consent_mode"	no
`typescript`	"true" \| "false"	no
`project`	string	no

setup.snippet

GET /v1/projects/{project}/setup/snippet – Install code with the project's real publishable key, API origin and proxy path.

Auth: secret key or user session · project:admin
Response: 200 JSON (SetupInstructions)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required
`framework`	"next-app" \| "next-pages" \| "react-vite" \| "astro" \| "wordpress" \| "webflow-html" \| "shopify" \| "other"	yes
`proxy`	"route-handler" \| "cloudflare-worker" \| "nginx" \| "netlify" \| "wordpress" \| "cname" \| "none"	no
`consent`	"none" \| "custom" \| "cookiebot" \| "usercentrics" \| "complianz" \| "borlabs" \| "google_consent_mode"	no
`typescript`	"true" \| "false"	no

setup.verify

POST /v1/projects/{project}/setup/verify – Verify an installation: fetch the page (SSRF-guarded), check snippet/proxy/CSP, look for recent events.

Auth: secret key or user session · project:admin
Response: 200 JSON (VerifyInstallationResult)
Body: application/json (VerifyInstallationInput)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

setup.status

GET /v1/projects/{project}/setup/status – Onboarding status per step, derived from real data (tracking, goals, ad platforms, conversions, Claude/MCP, team).

Auth: secret key or user session · analytics:read
Response: 200 JSON (SetupStatus)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

setup.progress

PATCH /v1/projects/{project}/setup – Wizard position, dismissal and manual step overrides (skip, re-open, team done).

Each key in steps needs one of the step's scopes (goals: config:write, ads: ads:write, conversions: project:admin, ai: analytics:read, team: org:admin); dismissed needs project:admin; lastStep alone needs analytics:read. Returns the fresh status.

Auth: secret key or user session · analytics:read
Response: 200 JSON (SetupStatus)
Body: application/json (SetupProgressUpdate)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

setup.installation

GET /v1/projects/{project}/setup/installation – Live installation check: hosts seen, SDK version, proxy, consent, custom events, last verification (test traffic included).

Auth: secret key or user session · analytics:read
Response: 200 JSON (SetupInstallation)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`since`	string	no

setup.prompts

GET /v1/projects/{project}/setup/prompts – Ready-made Claude Code prompts for this project (titles and descriptions).

Auth: secret key or user session · analytics:read
Response: 200 JSON (SetupPromptList)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`locale`	"de" \| "en"	no

setup.prompt

GET /v1/projects/{project}/setup/prompts/{kind} – One project-specific Claude Code prompt (never contains secrets).

Kinds install, events and server_conversions need config:write or project:admin; mcp_analysis, troubleshoot and connection_test need analytics:read.

Auth: secret key or user session · analytics:read
Response: 200 JSON (SetupPrompt)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)
`kind`	"install" \| "events" \| "server_conversions" \| "mcp_analysis" \| "troubleshoot" \| "connection_test"	yes

Query parameters:

Name	Type	Required
`stack`	"next-app" \| "next-pages" \| "react-vite" \| "astro" \| "wordpress" \| "webflow-html" \| "shopify" \| "other" \| "auto"	no
`site_url`	string	no
`proxy`	"auto" \| "on" \| "off"	no
`locale`	"de" \| "en"	no

setup.testConversion

POST /v1/projects/{project}/setup/test-conversion – Send one synthetic test conversion to a configured provider in its test mode and return the provider's answer.

Auth: secret key or user session · project:admin
Response: 200 JSON (SetupTestConversionResult)
Body: application/json (SetupTestConversion)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

setup.mcpActivity

GET /v1/projects/{project}/setup/mcp-activity – Newest MCP calls for this project (Claude connection test).

Auth: secret key or user session · analytics:read
Response: 200 JSON (SetupMcpActivity)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Query parameters:

Name	Type	Required	Description
`limit`	string	no

setup.detectStack

POST /v1/projects/{project}/setup/detect-stack – Guess the website's stack from its HTML (SSRF-guarded fetch of an allowed origin).

Auth: secret key or user session · analytics:read
Response: 200 JSON (SetupDetectStackResult)
Body: application/json (SetupDetectStack)

Path parameters:

Name	Type	Required	Description
`project`	string	yes	Project id, `project-slug` or `org-slug/project-slug` (URL-encode the slash as %2F)

Docs

Operation	Endpoint	Auth
`docs.openapi`	`GET /v1/openapi.json`	public
`docs.list`	`GET /v1/docs`	public
`docs.search`	`GET /v1/docs/search`	public
`docs.get`	`GET /v1/docs/{slug}`	public
`docs.getMarkdown`	`GET /v1/docs/{slug}.md`	public
`docs.reference`	`GET /docs/api`	public
`docs.referenceMarkdown`	`GET /docs/api.md`	public
`docs.llms`	`GET /llms.txt`	public
`docs.llmsFull`	`GET /llms-full.txt`	public

docs.openapi

GET /v1/openapi.json – OpenAPI 3.1 document.

Auth: public
Response: 200 JSON

docs.list

GET /v1/docs – Documentation index.

Auth: public
Response: 200 JSON

docs.search

GET /v1/docs/search – Full-text search over guides and the API reference.

Auth: public
Response: 200 JSON

Query parameters:

Name	Type	Required	Description
`q`	string	yes
`limit`	string	no

docs.get

GET /v1/docs/{slug} – One guide as markdown (slug with slashes URL-encoded or as path segments).

Auth: public
Response: 200 JSON (Doc)

Path parameters:

Name	Type	Required	Description
`slug`	string	yes

docs.getMarkdown

GET /v1/docs/{slug}.md – One guide as raw markdown (links point to other .md guides).

Auth: public
Response: 200 markdown

Path parameters:

Name	Type	Required	Description
`slug`	string	yes

docs.reference

GET /docs/api – Interactive API reference (Scalar) rendered from the OpenAPI document.

Auth: public
Response: 200 html

docs.referenceMarkdown

GET /docs/api.md – API reference as markdown (every endpoint with auth, scopes, parameters).

Auth: public
Response: 200 markdown

docs.llms

GET /llms.txt – llms.txt index of the documentation (https://llmstxt.org).

Auth: public
Response: 200 text

docs.llmsFull

GET /llms-full.txt – Every guide concatenated as markdown, for LLM context.

Auth: public
Response: 200 text

#API reference

#System

#system.health

#system.cron

#Ingest

#ingest.collect

#ingest.collectAlias

#ingest.clientConfig

#ingest.script

#ingest.sdkPackage

#Events

#ingest.serverEvents

#analytics.liveEvents

#events.catalog

#eventSchemas.upsert

#eventSchemas.delete

#events.validate

#Auth

#auth.signup

#auth.login

#auth.logout

#auth.me

#auth.sudo

#auth.magicLink

#auth.magicLinkVerify

#auth.password

#auth.invitationInfo

#auth.invitationAccept

#oauthGrants.mine

#Organizations

#orgs.list

#orgs.create

#orgs.get

#orgs.update

#orgs.delete

#audit.list

#oauthGrants.list

#oauthGrants.revoke

#Members

#members.list

#members.update

#members.remove

#invitations.list

#invitations.create

#invitations.revoke

#Keys

#keys.list

#keys.create

#keys.roll

#keys.revoke

#publishableKeys.list

#publishableKeys.create

#publishableKeys.roll

#proxyKeys.list

#proxyKeys.create

#proxyKeys.revoke

#publishableKeys.revoke

#Projects

#projects.list

#projects.create

#projects.get

#projects.update

#projects.delete

#projects.getConfig

#projects.updateConfig

#projects.status

#projects.purgeData

#Analytics

#analytics.overview

#analytics.timeseries

#analytics.funnel

#analytics.breakdown

#analytics.relevanceRanking

#analytics.pages

#analytics.scroll

#analytics.sections

#analytics.engagement

#analytics.clicks

#analytics.videos

#analytics.videoRetention

API reference

System

system.health

system.cron

Ingest

ingest.collect

ingest.collectAlias

ingest.clientConfig

ingest.script

ingest.sdkPackage

Events

ingest.serverEvents

analytics.liveEvents

events.catalog

eventSchemas.upsert

eventSchemas.delete

events.validate

Auth

auth.signup

auth.login

auth.logout

auth.me

auth.sudo

auth.magicLink

auth.magicLinkVerify

auth.password

auth.invitationInfo

auth.invitationAccept

oauthGrants.mine

Organizations

orgs.list

orgs.create

orgs.get

orgs.update

orgs.delete

audit.list

oauthGrants.list

oauthGrants.revoke

Members

members.list

members.update

members.remove

invitations.list

invitations.create

invitations.revoke

Keys

keys.list

keys.create

keys.roll

keys.revoke

publishableKeys.list

publishableKeys.create

publishableKeys.roll

proxyKeys.list

proxyKeys.create

proxyKeys.revoke

publishableKeys.revoke

Projects

projects.list

projects.create

projects.get

projects.update

projects.delete

projects.getConfig

projects.updateConfig

projects.status

projects.purgeData

Analytics

analytics.overview

analytics.timeseries

analytics.funnel

analytics.breakdown

analytics.relevanceRanking

analytics.pages

analytics.scroll

analytics.sections

analytics.engagement

analytics.clicks

analytics.videos

analytics.videoRetention