Agent access

An agent reaches Datalyr two ways. Both answer the same questions about one workspace. Both can change six 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 41 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. It can list, read, and run dashboards and analyses. Its Save to Reports, Add to dashboard, and Save as analysis buttons are a person’s clicks, not tools the model can call.

The 64 MCP tools

44 tools read. 19 tools change something or start work. report_missing_capability records a question no tool could answer, and reads and changes no data. 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 44 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`	Attributed conversions and revenue under a chosen model, by channel, source, campaign, ad set, or ad
`list_users`	Visitors and identified users, with an optional search
`get_user`	One user’s profile, sessions, journey, and conversions. Covers the last 90 days by default; pass `window_days` (up to 365) for longer history
`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
`analytics_query`	Any metric by up to 3 dimensions, filters, and a date range, with optional day, week, or month buckets and a previous-period comparison
`list_dimensions`	The dimension ids `analytics_query` can group and filter by
`get_dimension_values`	The real values of one dimension, most frequent first, with counts
`get_context`	Timezone, today’s date, reporting currency, connected sources with their last sync, attribution defaults, and plan
`search`	Metric ids, dimension ids, and exact campaign, ad, source, or event names that match a name you typed
`get_subscriptions`	Active subscriptions, trialing, cancel-scheduled, MRR, and ARR, or trials ending per day
`list_replay_sessions`	Recorded sessions of the last 31 days that match filters such as source, campaign, device, entry page type, and friction flags. 50 rows per page, without summaries. Needs session replay turned on
`get_replay_summary`	The written summary and flags of up to 20 recorded sessions. Needs session replay turned on
`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
`list_reports`	The saved reports on the workspace’s Reports page, in board order
`get_report`	One saved report: its kind, name, and definition
`run_report`	A saved report’s numbers for its default range or a range you pass
`list_dashboards`	The workspace’s dashboards, without their cards
`get_dashboard`	One dashboard: its range, filters, and cards. A deleted report’s card reads `report: null`.
`run_dashboard`	Every card’s numbers over the dashboard range, or a range and filters you pass
`list_analyses`	The workspace’s analyses, without their body or plans
`get_analysis`	One analysis: its Markdown body, plans, attached report ids, and range
`list_share_links`	The share links to an object: status, expiry, views, and the last 4 characters of the token. Never the URL.

Ask with analytics_query

analytics_query answers any question of the form metric by dimension, filter, and time. It takes a plan, not SQL. The workspace comes from your sign-in.

{
  "metrics": ["attributed_revenue", "attributed_conversions"],
  "dimensions": ["campaign"],
  "filters": [{ "dimension": "platform", "op": "eq", "value": "meta" }],
  "date_range": { "preset": "last_30_days" },
  "attribution": { "model": "last_touch", "window_days": 7 },
  "limit": 20
}

Rule	Detail
Attribution	`attributed_*` metrics need `attribution: {model, window_days}`. When the plan omits it, the workspace default applies. `meta.resolved.attribution` always names the model and window that ran.
Names	Confirm a campaign, source, or event name with `get_dimension_values` or `search` first. A misspelt value returns zero rows, not an error.
Unavailable	`meta.unavailable` lists metrics that were not measured. They are not zero.
Truncated	`meta.truncated: true` means the rows stop at `limit`. Narrow the query or page with `meta.next_cursor`.

Funnels, retention, cohort LTV, and one person’s journey keep their own tools: get_funnel, get_retention, get_ltv, and get_user.

The 19 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`
`create_report`	Saves a chart to the Reports page. Dry run by default.	`datalyr:write:reports`
`update_report`	Renames a saved report or changes its definition. Dry run by default.	`datalyr:write:reports`
`delete_report`	Deletes a saved report. Dry run by default. Undo restores it.	`datalyr:write:reports`
`create_dashboard`	Arranges saved reports on a dashboard with one range and optional filters. Dry run by default.	`datalyr:write:reports`
`update_dashboard`	Renames a dashboard, or replaces its range, filters, or card list. Dry run by default.	`datalyr:write:reports`
`delete_dashboard`	Deletes a dashboard. Dry run by default. Undo restores it.	`datalyr:write:reports`
`create_analysis`	Saves a Markdown write-up with the plans behind its numbers. Dry run by default.	`datalyr:write:reports`
`update_analysis`	Edits an analysis. Dry run by default.	`datalyr:write:reports`
`delete_analysis`	Deletes an analysis. Dry run by default. Undo restores it.	`datalyr:write:reports`
`create_share_link`	Creates a public, read-only link to a report, dashboard, or analysis. Dry run by default.	`datalyr:write:reports`
`revoke_share_link`	Turns a share link off for good. Dry run by default.	`datalyr:write:reports`

Write scopes

Scope	Allows	Consent page title
`datalyr:write:rules`	Create, edit, and delete conversion rules	Create, edit and delete conversion rules
`datalyr:write:links`	Create, edit, and delete trackable links	Create, edit and delete trackable links
`datalyr:write:reports`	Create, edit, delete, and reorder saved reports. Create, edit, and delete dashboards and analyses. Create and revoke share links. Reports only read data.	Create, edit, delete and share reports, dashboards and analyses
`datalyr:propose:scripts`	Submit a container-script draft for review	Propose container scripts for human approval (cannot publish them)

Any workspace member can use a write scope over OAuth. A named key with a write scope needs the owner to grant it. 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, trackable links, saved reports, dashboards, and analyses. It can create and revoke share links, and 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	A person grants every named key its scope list: in Settings → API, by approving a key request, or by OAuth consent. A key never mints a key. The original workspace Agent key never gains a scope.
Dry run is the default	The 17 rule, link, report, dashboard, analysis, and share-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. A share link is the exception: revoking it is final.
Creates take an `Idempotency-Key`	A retry with the same key and body returns the first response, not a second object. `POST /v1/share-links` ignores the header, so a retry creates a second link.
An agent sees a share URL once	Only the applied create returns it. Lists, the audit log, and dry runs never hold it. We look links up by a hash and keep the token encrypted, so the app’s Share popover can copy it again for a signed-in member.
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 data 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 five 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.
Read `meta.unavailable` before a query row	A metric listed there was not measured. `POST /v1/query` never prints it as `0`.
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, or `/events` returned `total_count_is_lower_bound: true`.	Page until `has_more` is `false`, or send `include_total=true` on `/events`.

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

Query

Workspace

Keys and approvals

Conversion rules

Trackable links

Saved reports

Dashboards, analyses and share links

Session replay

Exports

Which to pick

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

The 64 MCP tools

The 44 read tools

Ask with analytics_query

The 19 tools that write or start work

Write scopes

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 64 MCP tools

​The 44 read tools

​Ask with analytics_query

​The 19 tools that write or start work

​Write scopes

​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 64 MCP tools

The 44 read tools

Ask with analytics_query

The 19 tools that write or start work

Write scopes

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