Agent access

An agent reaches Datalyr two ways. Both answer the same questions about one workspace. Both can change two kinds of object when a person grants a write scope.

Way in	Credential	Best for
Hosted MCP server at `https://api.datalyr.com/mcp`	OAuth, scope `datalyr:read` plus any write scope a person grants	Claude, Codex, and any client that speaks MCP
Read and Write API at `https://api.datalyr.com/v1`	A named API key, `dk_agent_`	Your own code, scripts, and agent frameworks

Reading needs datalyr:read and nothing else. Writing needs a named key or an OAuth token that carries the matching write scope. The original workspace Agent key carries datalyr:read forever, so no key already in circulation gained write power.

Which to pick

Pick MCP when a person drives the client and can complete a browser sign-in. The token is short-lived, and no key is stored anywhere. Pick the API when code runs without a person present. See Authentication to create a key.

In-app chat is a third surface, and it never writes

The Datalyr dashboard has its own chat agent. It holds 24 read tools and no write tools. It authenticates with the workspace Agent key, which carries datalyr:read only. The panel has no consent screen, so nobody can grant it more.

The 35 MCP tools

27 tools read. 8 tools change something or start work. tools/list is the authority: read it at the start of a session and branch on what comes back. Do not hard-code the tool set.

The 27 read tools

Tool	Returns
`list_workspaces`	Every workspace you can access. Call this first.
`get_overview`	Visitors, pageviews, sessions, custom events, and a time series
`get_traffic`	A breakdown by referrer, campaign, or page
`get_devices`	A breakdown by browser, operating system, or device type
`get_locations`	A breakdown by country, region, or city
`get_events`	Raw events, filtered by name, campaign, country, page, or custom property
`list_event_names`	Distinct event names of the last 30 days
`list_event_properties`	Custom event properties this workspace sends, with a sample value and type
`get_realtime`	Active visitors, pages, events, revenue, and a minute timeline
`get_attribution`	Attribution by channel under a chosen model, with an unattributed bucket
`list_users`	Visitors and identified users, with an optional search
`get_user`	One user’s profile, sessions, journey, and conversions
`get_ads`	Provider-reported spend, delivery, conversions, and ROAS
`get_revenue`	Revenue, orders, subscriptions, refunds, AOV, and a time series
`get_commerce_metrics`	Certified revenue, spend, profit, margin, ROAS, and MER
`list_metrics`	The catalog of metric ids you can query, with units and availability
`query_metrics`	Up to 50 named metrics over a date range, with an optional comparison
`get_retention`	Person-grain retention cohorts, with active persons and revenue per period
`get_ltv`	Cohort LTV: cumulative revenue and revenue per acquired person, optionally split by first-touch acquisition channel
`get_funnel`	An ordered funnel over 2 to 5 event names, with per-step conversion rates
`get_tags`	Tracking-link tag counts and percentages
`get_workspace`	Name, domain, timezone, and connected platforms
`get_onboarding_status`	Plan, whether tracking ever sent an event, live sources, and the next steps
`get_usage`	Plan, current-period event and postback usage, and API usage
`search_docs`	Matching pages of this documentation, with a link and an excerpt
`get_script_proposals`	Container-script drafts an agent submitted, and what a human decided
`get_export_status`	One export job’s state, and its download URL once the file exists

The 8 tools that write or start work

Tool	Does	Scope
`create_conversion_rule`	Creates a conversion rule. Dry run by default.	`datalyr:write:rules`
`update_conversion_rule`	Edits a conversion rule. Dry run by default.	`datalyr:write:rules`
`delete_conversion_rule`	Deletes a conversion rule. Dry run by default.	`datalyr:write:rules`
`create_link`	Creates a trackable link. Dry run by default.	`datalyr:write:links`
`update_link`	Edits a trackable link. Dry run by default.	`datalyr:write:links`
`delete_link`	Deletes a trackable link. Dry run by default.	`datalyr:write:links`
`propose_container_script`	Submits a container-script draft for a human to review. It publishes nothing.	`datalyr:propose:scripts`
`create_export`	Starts an export job. It returns a job id, never data.	`datalyr:read`

The setup steps for Claude and Codex are on Connect Claude or Codex.

What an agent can change, and what stops it

An agent can change conversion rules and trackable links. It can draft a container script. It cannot do anything else. Tracking domains, filter settings, team membership, and billing have no agent surface at all.

Guard	Detail
Scopes are granted, never inherited	An owner creates a named key with an explicit scope list. The original workspace Agent key never gains one.
Dry run is the default	The six rule and link tools preview by default. Pass `dry_run: false` to apply.
A preview shows the real effect	A rule’s dry run names the platform, ad account, and asset the rule would fire to.
Every applied write is recorded	Read the log at `GET /v1/audit`. Each entry holds the state before the change.
Every applied write can be reversed	`POST /v1/audit/{auditId}/undo` restores that prior state under the original id.
Creates take an `Idempotency-Key`	A retry with the same key and body returns the first response, not a second object.
Container scripts are propose-only	No scope publishes a script, and no endpoint approves one. An owner or admin approves it in the dashboard.

A container script is arbitrary JavaScript on every page of your site, next to your checkout. That is why a leaked key can draft one and can never ship one.

Exports return a job, not a file

create_export answers with a job id. Poll get_export_status until the state is completed, then read download.url. Two clocks run on a finished export. The signed URL lasts one hour, so fetch it on use rather than storing it. The file itself is deleted seven days after creation.

What the HTTP API adds

Every MCP tool maps to a /v1 endpoint, so the API covers the same ground with three extras an agent framework often wants. It also carries routes MCP does not expose at all, including POST /v1/signup, GET /v1/audit, and the undo path.

Extra	Detail
Exact pagination	`/events` and `/users` return `limit`, `offset`, and `has_more`. See Errors and limits.
Rate-limit budget	Every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`.
An OpenAPI description	The `/v1` schema drives this section, so a client can generate its own bindings.

Reading a response safely

These four rules keep an agent from reporting a number that isn’t there.

Rule	Why
Treat `503` as unknown, never as zero	`/ads` and `/commerce-metrics` fail loudly rather than answer with a wrong total.
Read `complete` before you read a total	A `200` with `complete: true` is the only answer that covers the range.
Read `attribution_source`, not `source`	`source` carries the transport during the events-source rename.
Page until `has_more` is `false`	A full page is not proof that more rows exist, and a short page is not proof that they don’t.

Sending events is a different credential

Reading and writing do not share a key or a host. An agent that also sends events uses the write key against https://ingest.datalyr.com. See Ingest API. The write key reads nothing. Never point POST /attribution/lookup at an email address a user typed into your own product.

Machine-readable docs

Path	Holds
`https://docs.datalyr.com/llms.txt`	A short site description and the pages an agent needs first
`https://docs.datalyr.com/llms-full.txt`	The same index, plus the full text of the MCP, authentication, and errors pages
Any page path plus `.md`	That one page as Markdown, for example `/api-reference/authentication.md`

Verify

Ask your client: List my Datalyr workspaces.
Confirm the reply names the workspace you expect.
Run the curl on Authentication with your Agent key.
Confirm the response names the same workspace.

When it doesn’t work

Symptom	Cause	Fix
The client lists no Datalyr tools	The connector is added but not connected.	Open the connector and sign in to Datalyr.
A tool you expected is missing	Your token or key does not carry the scope that tool needs.	Read `tools/list` and ask an owner for a key with that scope.
`403` with `insufficient_scope`	The route needs a scope your credential does not hold.	The response names it in `required_scope`. Ask an owner for it.
A write applied when you wanted a preview	You passed `dry_run: false`.	Reverse it with `POST /v1/audit/{auditId}/undo`.
`401` from `/v1`	You sent a `dk_` write key.	Send the `dk_agent_` key.
`429` on every request	The key passed 100 requests in 60 seconds.	Wait for `Retry-After`, which is `60`.
`429` sooner than expected, with `X-RateLimit-Degraded: 1`	Our rate-limit store is unreachable, so reads run under a smaller standby limit.	Slow down and retry. See Errors and limits.
A total looks too small	The agent read one page and stopped.	Page until `has_more` is `false`.

Connect Claude or Codex: add the MCP server to your client.
API reference: every endpoint and its parameters.
Ingest API: send events over raw HTTP.

Agents and MCP

API Reference

Analytics

Events and users

Attribution and revenue

Cohorts and funnels

Metrics

Workspace

Conversion rules

Trackable links

Exports

Which to pick

In-app chat is a third surface, and it never writes

The 35 MCP tools

The 27 read tools

The 8 tools that write or start work

What an agent can change, and what stops it

Exports return a job, not a file

What the HTTP API adds

Reading a response safely

Sending events is a different credential

Machine-readable docs

Verify

When it doesn’t work

Next

​Which to pick

​In-app chat is a third surface, and it never writes

​The 35 MCP tools

​The 27 read tools

​The 8 tools that write or start work

​What an agent can change, and what stops it

​Exports return a job, not a file

​What the HTTP API adds

​Reading a response safely

​Sending events is a different credential

​Machine-readable docs

​Verify

​When it doesn’t work

​Next

Which to pick

In-app chat is a third surface, and it never writes

The 35 MCP tools

The 27 read tools

The 8 tools that write or start work

What an agent can change, and what stops it

Exports return a job, not a file

What the HTTP API adds

Reading a response safely

Sending events is a different credential

Machine-readable docs

Verify

When it doesn’t work

Next