# Datalyr

> Datalyr is a marketing attribution and analytics platform. It captures web, mobile, and
> server events, resolves them to a person, joins them to ad spend and revenue, and
> delivers conversions back to ad platforms. Agents reach it three ways: the hosted MCP
> server at `https://api.datalyr.com/mcp` (OAuth, 35 tools), the HTTP API at
> `https://api.datalyr.com/v1` (bearer keys, reads plus scoped writes), and the in-app
> chat assistant. Every docs page is also available as Markdown: append `.md` to its
> path. The full text of the most load-bearing pages is at
> https://docs.datalyr.com/llms-full.txt.

## Facts an agent needs first

- Auth: send `Authorization: Bearer dk_agent_...`. The workspace Agent key reads everything. Named keys add write scopes: `datalyr:write:rules`, `datalyr:write:links`, `datalyr:propose:scripts`. A missing scope returns `403` with `code: insufficient_scope`.
- Writes preview by default over MCP: every write tool sends `dry_run: true` unless you set it false. A dry run returns the exact diff, including which ad platform and pixel a conversion rule would fire to. Over raw HTTP, `dry_run` defaults to false.
- Every applied write creates an audit entry with the prior state. `POST /v1/audit/{id}/undo` reverses it.
- Container scripts never apply through the API. `propose_container_script` files a draft; an owner or admin approves it in the dashboard.
- Rate limits: 100 requests per 60 seconds per key, `X-RateLimit-Limit` and `X-RateLimit-Remaining` on every response. Writes have their own 20 per 60 seconds bucket. `X-RateLimit-Degraded: 1` means the limit store is unreachable and a smaller standby cap applies.
- A `503` with `unavailable` in the body means the data source did not answer. It never means zero. Do not report an unavailable metric as a measured zero.
- Dates: instant-based endpoints take ISO 8601 UTC. `/ads` takes provider-local `YYYY-MM-DD` labels because each ad account owns its reporting calendar. `/commerce-metrics` takes exact UTC-hour instants.
- Attribution taxonomy: 9 channel buckets (meta, google, tiktok, snapchat, organic, direct, referral, email, other). `/v1/attribution`, `/v1/ltv?by=channel`, and the dashboard all use the same names.
- Multi-platform ad money is not blendable. `/ads` returns per-provider currency, conversion definitions, and freshness. Never add spend across platforms when the response warns against it.

## Agent and MCP access

- [Agent access](https://docs.datalyr.com/api-reference/agents.md): What an agent can read and change, the 35 MCP tools, the write scopes, and the four rules that keep a reported number honest.
- [Connect Claude or Codex](https://docs.datalyr.com/datalyr-mcp.md): Set up the hosted MCP server at `https://api.datalyr.com/mcp` over OAuth, with no stored key.
- [Agent-driven setup](https://docs.datalyr.com/developer/agent-driven-setup.md): How an agent takes a prospect from `POST /v1/signup` to a verified install, and the four things only a person can do.
- MCP read tools: `list_workspaces`, `get_overview`, `get_traffic`, `get_devices`, `get_locations`, `get_events`, `list_event_properties`, `list_event_names`, `get_realtime`, `get_attribution`, `list_users`, `get_user`, `get_ads`, `get_revenue`, `get_commerce_metrics`, `list_metrics`, `query_metrics`, `get_retention`, `get_ltv`, `get_funnel`, `get_tags`, `get_workspace`, `get_onboarding_status`, `get_usage`, `search_docs`, `get_script_proposals`, `get_export_status`.
- MCP write and start-work tools: `create_conversion_rule`, `update_conversion_rule`, `delete_conversion_rule`, `create_link`, `update_link`, `delete_link`, `propose_container_script`, `create_export`.
- Read `tools/list` at connect time for the current set. Do not hard-code tool names or counts.

## HTTP API — reference pages

- [API reference](https://docs.datalyr.com/api-reference/index.md): Every endpoint, what each returns, which ones change something and under which scope, and the date rules.
- [Authentication](https://docs.datalyr.com/api-reference/authentication.md): The Agent key, named keys with write scopes, bearer usage, and the `401` body.
- [Errors and limits](https://docs.datalyr.com/api-reference/errors-and-limits.md): Every status code with cause and fix, rate limits and their headers, parameter caps, pagination, and limiter-outage behavior.
- [API keys](https://docs.datalyr.com/account/api-keys.md): The two workspace keys, named keys that carry write scopes, reveal-once creation, and rotation.
- [TypeScript client](https://docs.datalyr.com/api-reference/typescript-client.md): `npm install @datalyr/client` — a typed client for every endpoint, with retries and Idempotency-Key support.

## HTTP API — read endpoints

- `GET /v1/overview`: Visitors, pageviews, sessions, conversions, bounce rate, with a time series.
- `GET /v1/traffic`: Referrer, campaign, or top-page breakdown.
- `GET /v1/devices`: Browser, OS, or device type breakdown.
- `GET /v1/locations`: Country, region, or city breakdown.
- `GET /v1/realtime`: Live visitors in the last 1 to 60 minutes.
- `GET /v1/events`: Raw events with filters, `property_filters` (JSON property predicates, 31-day max range), `limit`, and `offset` with an exact `has_more`.
- `GET /v1/events/properties`: Sampled discovery of event property keys, per event name.
- `GET /v1/event-names`: Distinct event names from the last 30 days.
- `GET /v1/users`: People, most recent first, with search and offset paging.
- `GET /v1/users/{id}`: One person's sessions, events, and conversions.
- `GET /v1/attribution`: Channel-grain attribution. Models: `last_touch`, `first_touch`, `linear`, `time_decay`. `window_days` 1 to 90. Falls back to workspace preferences.
- `GET /v1/ads`: Provider-certified spend, delivery, conversions, and ROAS from Meta, Google, and TikTok. Cursor paging. Not blendable across providers.
- `GET /v1/revenue`: Revenue from Stripe, Shopify, RevenueCat, and Superwall.
- `GET /v1/commerce-metrics`: Certified commerce metrics. Prefer this over `/revenue` for business performance questions.
- `POST /v1/metrics`: Batch query of 1 to 50 metric ids from the 160-metric catalog, with optional comparison window.
- `GET /v1/metrics/catalog`: Every queryable metric id with unit, platform, and availability.
- `GET /v1/retention`: Cohort retention grid. Granularity day, week, or month. Activity retention at person grain.
- `GET /v1/ltv`: Cohort lifetime value with exact payer counts. `by=channel` splits by acquisition channel.
- `GET /v1/funnel`: 2 to 5 ordered steps through `windowFunnel`. Visitor grain, 90-day lookback.
- `GET /v1/tags`: Custom tag analytics.
- `GET /v1/workspace`: Workspace metadata and connected platforms.
- `GET /v1/usage`: Plan, event quota, and per-day API usage counts.
- `GET /v1/onboarding`: Setup checklist: tracking state, connections, and next steps.
- `GET /v1/docs/search`: Search these docs. Returns titles, URLs, and excerpts.
- `GET /v1/exports`, `GET /v1/exports/{id}`: Export job status and a one-hour download URL when complete.
- `GET /v1/rules`, `GET /v1/links`, `GET /v1/scripts/proposals`, `GET /v1/audit`: List conversion rules, trackable links, script proposals, and write-audit entries.

## HTTP API — endpoints that change something

- `POST /v1/exports`: Start a CSV or NDJSON export of events, users, or attribution. Read scope. Files expire after 7 days.
- `POST /v1/rules`, `PATCH /v1/rules/{id}`, `DELETE /v1/rules/{id}`: Conversion rule writes. Scope `datalyr:write:rules`. Supports `dry_run` and `Idempotency-Key`. The diff names the exact postback target.
- `POST /v1/links`, `PATCH /v1/links/{id}`, `DELETE /v1/links/{id}`: Trackable link writes. Scope `datalyr:write:links`.
- `POST /v1/scripts/proposals`: File a container-script draft for human review. Scope `datalyr:propose:scripts`. No API path applies a script.
- `POST /v1/audit/{id}/undo`: Reverse an applied write from its stored prior state.
- `POST /v1/signup`: Unauthenticated. Starts email verification for a new account. A person verifies, pays, and creates the workspace. No API path creates a workspace or key without payment.

## Sending events

- [Ingest API](https://docs.datalyr.com/api-reference/ingest.md): The raw HTTP contract for `POST ingest.datalyr.com/track`: headers, body fields, batching, duplicates, and status codes. Attribution parameters go inside `properties`.
- [Web SDK](https://docs.datalyr.com/sdk-reference/web.md): Every `dl.js` method, config option, and transport limit for browser tracking.
- [Node.js SDK](https://docs.datalyr.com/sdk-reference/node.md): The server SDK, its wire format, and its retry behavior.
- [iOS SDK](https://docs.datalyr.com/sdk-reference/ios.md): Swift setup, attribution, SKAdNetwork, and the full method reference.
- [React Native SDK](https://docs.datalyr.com/sdk-reference/react-native.md): React Native setup, install attribution, and the full method reference.

## Getting data flowing

- [Choose your setup](https://docs.datalyr.com/getting-started/choose-your-setup.md): Which install path fits a site, a store, or an app.
- [Install web tracking](https://docs.datalyr.com/getting-started/install-web-tracking.md): Add the snippet to a site and start recording pageviews.
- [Install on Shopify](https://docs.datalyr.com/installation/shopify.md): Store setup with the app and the pixel.
- [Install mobile tracking](https://docs.datalyr.com/installation/mobile.md): Add the iOS or React Native SDK and capture installs.
- [Identity](https://docs.datalyr.com/advanced/identity.md): How `visitor_id`, `user_id`, and `distinct_id` differ, and when to call `identify()`.
- [Custom events](https://docs.datalyr.com/advanced/custom-events.md): Naming, properties, and value fields for events you define.
- [Verify your setup](https://docs.datalyr.com/getting-started/verify-your-setup.md): Prove that events, revenue, and attribution all arrive.

## Revenue sources

- [Revenue overview](https://docs.datalyr.com/revenue/index.md): Which platforms Datalyr reads revenue from and how they combine.
- [Shopify](https://docs.datalyr.com/revenue/shopify.md), [Stripe](https://docs.datalyr.com/revenue/stripe.md), [Whop](https://docs.datalyr.com/revenue/whop.md), [RevenueCat](https://docs.datalyr.com/revenue/revenuecat.md), [Superwall](https://docs.datalyr.com/revenue/superwall.md), [CheckoutChamp](https://docs.datalyr.com/revenue/checkoutchamp.md): Per-platform connection and what each one reports.
- [Subscriptions](https://docs.datalyr.com/revenue/subscriptions.md), [Refunds](https://docs.datalyr.com/revenue/refunds.md), [Profit](https://docs.datalyr.com/revenue/profit.md): How recurring revenue, refunds, and margin behave in reports.

## Ad platforms and delivery

- [Integrations overview](https://docs.datalyr.com/integrations/index.md): Every connected platform in one table.
- [Meta Ads](https://docs.datalyr.com/integrations/meta-ads.md), [Google Ads](https://docs.datalyr.com/integrations/google-ads.md), [TikTok Ads](https://docs.datalyr.com/integrations/tiktok-ads.md), [Snapchat Ads](https://docs.datalyr.com/integrations/snapchat-ads.md), [OpenAI Ads](https://docs.datalyr.com/integrations/openai-ads.md), [Klaviyo](https://docs.datalyr.com/integrations/klaviyo.md), [Apple SKAdNetwork](https://docs.datalyr.com/integrations/apple-skadnetwork.md): Connection, spend sync, and conversion delivery per platform.
- [Conversion delivery](https://docs.datalyr.com/advanced/conversion-delivery.md): How conversion rules send events back to ad platforms, and what a webhook target receives.
- [Attribution](https://docs.datalyr.com/attribution/index.md): Models, windows, and how a conversion resolves to a channel.

## Product surfaces

- [Dashboard](https://docs.datalyr.com/product/dashboard.md), [Events](https://docs.datalyr.com/product/events.md), [Live](https://docs.datalyr.com/product/live.md), [Users](https://docs.datalyr.com/product/users.md), [Conversions](https://docs.datalyr.com/product/conversions.md), [Reports](https://docs.datalyr.com/product/reports.md), [Tracking links](https://docs.datalyr.com/product/tracking-links.md), [AI chat](https://docs.datalyr.com/product/ai-chat.md): What each in-app surface shows and how it maps to the API.

## Account and workspace

- [Workspace settings](https://docs.datalyr.com/account/workspace-settings.md), [Domains](https://docs.datalyr.com/account/domains.md), [Team members](https://docs.datalyr.com/account/team-members.md), [Billing](https://docs.datalyr.com/account/billing.md), [Usage](https://docs.datalyr.com/account/usage.md), [Delete account](https://docs.datalyr.com/account/delete-account.md): Administration, roles, quotas, and data removal.
- [First-party tracking](https://docs.datalyr.com/advanced/first-party-tracking.md), [Cross-domain tracking](https://docs.datalyr.com/advanced/cross-domain-tracking.md), [Filters](https://docs.datalyr.com/advanced/filters.md), [Privacy](https://docs.datalyr.com/advanced/privacy.md), [Health and wellness redaction](https://docs.datalyr.com/advanced/health-wellness-redaction.md): Custom domains, multi-site identity, exclusions, and compliance.

## Troubleshooting

- [No events](https://docs.datalyr.com/troubleshooting/no-events.md): Symptom, cause, and fix when nothing reaches Datalyr.
- [Missing revenue](https://docs.datalyr.com/troubleshooting/missing-revenue.md), [Missing attribution](https://docs.datalyr.com/troubleshooting/missing-attribution.md), [Integration errors](https://docs.datalyr.com/troubleshooting/integration-errors.md), [Data differences](https://docs.datalyr.com/troubleshooting/data-differences.md), [Conversion delivery](https://docs.datalyr.com/troubleshooting/conversion-delivery.md): The other five failure classes with checks in order.

## Use cases

- [Shopify stores](https://docs.datalyr.com/use-cases/shopify.md), [Checkout funnels](https://docs.datalyr.com/use-cases/checkout-funnels.md), [Stripe SaaS](https://docs.datalyr.com/use-cases/stripe.md), [Mobile apps](https://docs.datalyr.com/use-cases/mobile.md), [Health and wellness](https://docs.datalyr.com/use-cases/health-wellness.md), [Creators on Whop](https://docs.datalyr.com/use-cases/creators-whop.md), [Lead generation](https://docs.datalyr.com/use-cases/lead-generation.md): End-to-end setups per business type.

## Optional

- [Full text](https://docs.datalyr.com/llms-full.txt): This index plus the complete text of the MCP, authentication, and errors pages.