API reference

The Datalyr API hands you one workspace’s analytics, attribution, revenue, and workspace data as JSON. Most endpoints read, and a read changes nothing. A small, scoped set of endpoints changes conversion rules and trackable links, or drafts a container script.

https://api.datalyr.com/v1

Every /v1 endpoint needs an Agent key, with one exception: POST /signup needs no credential at all. See Authentication. Each endpoint that changes something needs a named key carrying that endpoint’s scope. See Agent access.

Read endpoints

Each endpoint has its own page in this section, with the full parameter list and the response schema. None in the last column means the endpoint takes no required parameter.

Method	Path	Returns	Required
`GET`	`/overview`	`visitors_total`, `pageviews_total`, `sessions_total`, `custom_events_total`, `custom_event_counts`, `time_series`	`start_date`, `end_date`
`GET`	`/traffic`	Referrer, campaign, or page rows with `name`, `count`, `percentage`	`start_date`, `end_date`
`GET`	`/devices`	Browser, OS, or device-type rows with `name`, `count`, `percentage`	`start_date`, `end_date`
`GET`	`/locations`	Country, region, or city rows with `name`, `count`, `percentage`	`start_date`, `end_date`
`GET`	`/realtime`	`active_visitors`, `pageviews`, `events`, `revenue`, up to 50 `visitors`, `timeline`	None
`GET`	`/events`	Raw event rows, `total_count`, `has_more`, `limit`, `offset`	`start_date`, `end_date`
`GET`	`/events/properties`	Custom `event_data` keys per event name, each with a count, a distinct-value count, a sample, and a type	None
`GET`	`/event-names`	Distinct event names of the last 30 days, plus `integrations`	None
`GET`	`/users`	User rows, `total_count`, `has_more`, `limit`, `offset`	`start_date`, `end_date`
`GET`	`/users/{userId}`	`user`, `sessions`, `conversions`	`userId` in the path
`GET`	`/retention`	Person-grain cohorts, one row per elapsed period, with active persons, retention rate, and revenue	None
`GET`	`/ltv`	Cohort revenue per period, cumulative revenue, and cumulative revenue per acquired person	None
`GET`	`/funnel`	Ordered funnel over 2 to 5 event names, with per-step conversion rates	`steps`
`GET`	`/attribution`	`campaigns` grouped by UTM, with visitors, conversions, revenue, rates	`start_date`, `end_date`
`GET`	`/ads`	Provider-reported spend, delivery, conversions, and ROAS per ad entity	`start_date`, `end_date` or `date_from`, `date_through`
`GET`	`/revenue`	Per-platform and combined revenue, orders, subscriptions, refunds, AOV	`start_date`, `end_date`
`GET`	`/commerce-metrics`	Policy-governed revenue, spend, profit, margin, ROAS, MER, completeness	`start_date`, `end_date`
`POST`	`/metrics`	Up to 50 catalog metrics over one range, with an optional preceding window	A JSON body
`GET`	`/metrics/catalog`	Every metric id `POST /metrics` accepts, with unit, category, and availability	None
`GET`	`/tags`	Tracking-link tag rows with `tag`, `count`, `percentage`, `source`	`start_date`, `end_date`
`GET`	`/workspace`	`id`, `name`, `domain`, `timezone`, `connected_platforms`	None
`GET`	`/usage`	`events_used`, `events_limit`, `postbacks_used`, `postbacks_limit`, `period_start`, `period_end`, `plan`	None
`GET`	`/onboarding`	What is set up in this workspace, and the `next_steps` a person still has to take	None
`GET`	`/docs/search`	Matching sections of this documentation, each with a link and an excerpt	`q`
`GET`	`/exports`	Recent export jobs and their status, newest first. No download URLs	None
`GET`	`/exports/{exportId}`	One job’s status, plus a signed `download` URL once the file exists	`exportId` in the path
`GET`	`/rules`	Every conversion rule in the workspace	None
`GET`	`/links`	Every trackable link in the workspace	None
`GET`	`/scripts/proposals`	Container-script drafts, newest first, with the verdict a human reached	None
`GET`	`/scripts/proposals/{proposalId}`	One draft as submitted, plus the reviewer’s note	`proposalId` in the path
`GET`	`/audit`	Applied writes, newest first, each carrying the state it replaced	None

POST /metrics is a read that takes a body, because 50 metric ids do not belong in a query string.

Endpoints that change something

These need a named key carrying the scope in the last column. The original per-workspace Agent key resolves to datalyr:read alone, so it reads every route above and changes none of these.

Method	Path	Does	Scope
`POST`	`/rules`	Creates a conversion rule	`datalyr:write:rules`
`PATCH`	`/rules/{ruleId}`	Changes the fields you send, and no others	`datalyr:write:rules`
`DELETE`	`/rules/{ruleId}`	Deletes a conversion rule	`datalyr:write:rules`
`POST`	`/links`	Creates a trackable link	`datalyr:write:links`
`PATCH`	`/links/{linkId}`	Changes a link’s name, destination, or UTM parameters	`datalyr:write:links`
`DELETE`	`/links/{linkId}`	Deletes a trackable link	`datalyr:write:links`
`POST`	`/scripts/proposals`	Records a container-script draft. It installs nothing	`datalyr:propose:scripts`
`POST`	`/exports`	Starts an export job. It returns a job id, never data	`datalyr:read`
`POST`	`/audit/{auditId}/undo`	Restores the state one audit entry replaced	The scope of the write being reversed

Four rules govern every one of them.

Rule	Detail
`dry_run`	Every one accepts it. Over raw HTTP it defaults to `false`, because a `DELETE` you sent is a `DELETE` you meant. Send `dry_run: true` to read the exact change first. The MCP write tools default it to `true`.
`Idempotency-Key`	`POST` accepts this header. An identical retry inside 24 hours returns the first response with `Idempotent-Replay: true`, rather than a second object.
Audit	Every applied write records what changed and the state it replaced, whether it came from this API or the dashboard. Read `GET /audit`.
Undo	`POST /audit/{auditId}/undo` puts the resource back. It refuses rather than guesses: it will not reverse a create, run twice, or restore over a resource that has since been deleted.

A container script is arbitrary JavaScript on every page of your site. That is why POST /scripts/proposals only drafts one: no scope publishes a script, and no endpoint approves one. An owner or admin approves it in the dashboard. POST /signup is the only route here that needs no key. It sends one verification email and returns {"status": "verification_sent"} for a new address and an existing one alike. Nothing is created until the recipient opens the link. See Agent-driven setup.

Date parameters

Most reporting endpoints take a date range. /realtime, /event-names, /users/{userId}, /workspace, and /usage take none. /retention, /ltv, and /funnel accept a range and fall back to a default when you omit it, so read each endpoint’s own page for its rule. The table below covers the endpoints that require both dates.

Parameter	Rule
`start_date`	Inclusive ISO 8601 instant. Required.
`end_date`	Inclusive ISO 8601 instant. Required.

A missing or unparseable date returns 400 with {"error":"start_date and end_date required (ISO 8601)"}. /commerce-metrics is stricter. Both instants must land on an exact UTC hour. end_date is exclusive, cannot be in the future, and cannot sit more than 366 days after start_date. /ads accepts a second, provider-local form: date_from and date_through as YYYY-MM-DD. A request that sends both forms returns 400.

Response format

Every response is application/json and carries Access-Control-Allow-Origin: *. Every error carries a single error string. /ads, /commerce-metrics, and the cost-import routes add a machine-readable code or reason. See Errors and limits.

Other routes on api.datalyr.com

These four routes sit outside /v1, and each takes a different credential.

Method	Path	Credential	Purpose
`GET`	`/health`	None	Returns `{"status":"ok"}`.
`POST`	`/mcp`	OAuth access token, scope `datalyr:read`	Hosted MCP server. See Connect Claude or Codex.
`POST`	`/attribution/lookup`	Write key in `X-Datalyr-API-Key`	Resolves web attribution for one email address. The mobile SDKs call it for themselves. Not a read route for your backend.
`POST`	`/attribution/deferred-lookup`	Write key in `X-Datalyr-API-Key`	Resolves a web session by client IP after an app install. The mobile SDKs call it.

Two POST routes exist at /v1/shopify/economics/cost-imports/validate and /v1/shopify/economics/cost-imports/apply. We run both of them, so an Agent key on its own returns 403.

Verify your access

Copy your Agent key from Settings → API.
Run the request below in a terminal.

curl "https://api.datalyr.com/v1/workspace" \
  --header "Authorization: Bearer dk_agent_YOUR_KEY"

The response names your workspace:

{
  "id": "ws_public_id",
  "name": "Acme",
  "domain": "acme.com",
  "timezone": "America/Chicago",
  "connected_platforms": [{ "provider": "stripe", "status": "active" }]
}

When it doesn’t work

Symptom	Cause	Fix
`401` and `Invalid or missing Agent API key`	You sent a write key, or no key at all.	Send the `dk_agent_` key from Settings → API.
`404` and `Not found`	The path is not one of the endpoints above.	Compare your path with the tables. Every path starts with `/v1`.
`405` and `Method not allowed`	The path exists, but not for the method you sent.	Use the method the tables above name for that path.
`403` and `insufficient_scope`	Your key does not carry the scope that endpoint needs.	Read `required_scope` on the response. Ask an owner for a key that holds it.
`200` with empty arrays and zero totals	The date range holds no data.	Widen the range. Confirm that events arrive in Events.

Authentication: create a key and send it correctly.
Errors and limits: every status code and the rate limit.
Agent access: the write scopes, the dry run, and the undo path.
Connect Claude or Codex: read the same data without handling a key.

Agents and MCP

Analytics

Events and users

Attribution and revenue

Cohorts and funnels

Metrics

Workspace

Conversion rules

Trackable links

Exports

API reference

Read endpoints

Endpoints that change something

Date parameters

Response format

Other routes on api.datalyr.com

Verify your access

When it doesn’t work

Next

​Read endpoints

​Endpoints that change something

​Signup takes no credential

​Date parameters

​Response format

​Other routes on api.datalyr.com

​Verify your access

​When it doesn’t work

​Next

Read endpoints

Endpoints that change something

Signup takes no credential

Date parameters

Response format

Other routes on api.datalyr.com

Verify your access

When it doesn’t work

Next