Read API

The Read API hands you one workspace’s analytics, attribution, revenue, and workspace data as JSON. It’s read-only, so nothing you call here changes your data.

https://api.datalyr.com/v1

Every /v1 endpoint uses GET, and every one needs an Agent key. See Authentication.

Endpoints

Sixteen endpoints exist. Nothing else under /v1 returns data.

Method	Path	Returns	Required query
`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`	`/event-names`	Distinct event names of the last 30 days, plus `integrations`	None
`GET`	`/users`	User rows, `total_count`, `has_more`	`start_date`, `end_date`
`GET`	`/users/{userId}`	`user`, `sessions`, `conversions`	None
`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`
`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

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 query parameter.

Date parameters

Eleven endpoints take a date range. /realtime, /event-names, /users/{userId}, /workspace, and /usage take none.

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.
`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 sixteen above.	Compare your path with the table. Every path starts with `/v1`.
`405` and `Method not allowed`	You sent `POST`, `PUT`, or `DELETE`.	Use `GET`.
`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.
Connect Claude or Codex: read the same data without handling a key.

API Reference

Analytics

Events and users

Attribution and revenue

Workspace

Endpoints

Date parameters

Response format

Other routes on api.datalyr.com

Verify your access

When it doesn’t work

Next

​Endpoints

​Date parameters

​Response format

​Other routes on api.datalyr.com

​Verify your access

​When it doesn’t work

​Next

Endpoints

Date parameters

Response format

Other routes on api.datalyr.com

Verify your access

When it doesn’t work

Next