> ## Documentation Index > Fetch the complete documentation index at: https://docs.datalyr.com/llms.txt > Use this file to discover all available pages before exploring further. # List queryable metrics > Discover every metric id `POST /metrics` accepts, with its unit, category and availability. A metric with `supported: false` resolves but never queries a source: it returns an explicit `unavailableReason` instead of a number. Cached for five minutes. ## OpenAPI ````yaml /api-reference/read-api.yaml get /metrics/catalog openapi: 3.1.0 info: title: Datalyr API version: 1.0.0 description: >- Read analytics, attribution, revenue and workspace data from Datalyr, and change conversion rules, trackable links and container-script drafts under an explicit write scope. servers: - url: https://api.datalyr.com/v1 security: - bearerAuth: [] tags: - name: Analytics - name: Events and users - name: Attribution and revenue - name: Workspace - name: Signup and onboarding description: >- The two routes an agent needs to take a prospect from nothing to a working install: one to start a signup, one to check what is still missing. **Agents sign up. Humans pay.** `POST /signup` is the only unauthenticated route in this API, and the only thing it does is send a verification email. It does not create an account, a workspace, a plan or an API key, and no parameter makes it. The person who reads that email verifies it, chooses a plan, and completes an Autumn-hosted Stripe checkout in their own browser. Only then does a workspace exist, and only then can a key be minted. An agent never handles a payment credential and cannot complete a checkout on anyone's behalf. **Throttled instead of captcha-gated.** A captcha proves a human is present, which is the opposite of this endpoint's premise. `POST /signup` is capped per client IP and per email address instead. Exceeding either returns `429` with a `Retry-After`; the limiter failing returns `503`, and never lets a request through. **No account-existence oracle.** An accepted `POST /signup` always answers `{"status": "verification_sent"}`, whether or not the address already has a Datalyr account. Do not infer anything about the address from the response. **`GET /onboarding` is the checklist.** It needs an Agent key, so it only works once a workspace exists — that is, after payment. Read `next_steps` and drive the human through them; re-read it to confirm each one landed. - name: Documentation description: >- Search the published Datalyr documentation. The only routes here that read content outside your workspace. - name: Exports description: >- Ask for a file instead of a page. An export runs asynchronously and produces a CSV or NDJSON object you download with a temporary link. **It is a job, not a response.** `POST /exports` returns `202` with a job id and no data — an export can scan a year of events and take minutes, which is longer than any HTTP request should live. Poll `GET /exports/{exportId}` until `status` is `completed`, then read `download.url`. **Scope.** `datalyr:read`, the same scope every other read on this page needs — including the original per-workspace Agent key. An export returns rows you can already fetch through `GET /events` or `GET /users`; it does not change anything you configured, so it does not require a write scope. **The download link is temporary and so is the file.** `download.url` is a signed URL valid for one hour from the moment you polled; poll again for a fresh one. The file itself is deleted seven days after the export was created (`expires_at`), after which the job reads `expired` and must be re-run. Treat the URL as a credential: anyone holding it can download the file until it expires. **Limits.** One export covers at most 366 days and one million rows (users exports: 100,000, the bound of the person-grain query). Hitting the row cap sets `truncated: true` on the finished job rather than failing it — you get the rows that fit and are told the range is not fully covered. A workspace may have five exports queued or running at once. **What the files contain.** `events` mirrors `GET /events` column for column; `users` mirrors `GET /users`; `attribution` is the channel-grain summary from `GET /attribution`, one row per channel plus an `unattributed` row. Filters are an allowlist per type — an unrecognized filter is rejected rather than ignored, so you never receive more rows than you asked for without being told. - name: Write API description: >- Create, change and delete conversion rules and trackable links, reverse any of it, and propose container scripts for a human to approve. **Two tiers, and the difference is deliberate.** Conversion rules and trackable links are direct writes. Container scripts are **propose-only**: `POST /scripts/proposals` records a draft and nothing else. No scope publishes a script, and there is no endpoint that approves one — an owner or admin approves it in the Datalyr dashboard, and only then does the script exist. A container script is arbitrary JavaScript injected into every page of the customer's site, so a key that could publish one would turn a leaked key into a supply-chain compromise rather than a data-access problem. **Scopes.** These routes need a named API key carrying an explicit write scope: `datalyr:write:rules` for conversion rules, `datalyr:write:links` for trackable links, `datalyr:propose:scripts` to draft a container script. The original per-workspace Agent key does not have them and never will — it resolves to `datalyr:read` alone, so it reads every route in this spec and writes none of them. Mint a named key with the scopes you want; a request without the right one returns `403` with `code: insufficient_scope` and the `required_scope` it wanted. **Dry run.** Every mutation accepts `dry_run`. A dry run validates the request, reads whatever it needs to describe the outcome, and returns the exact change it would make — including, for a conversion rule, which platform, ad account and pixel the rule would send conversions to. It writes nothing: no row, no audit entry, no edge redirect, no idempotency record. It defaults to `false` over raw HTTP, because a `DELETE` you sent is a `DELETE` you meant. The MCP write tools default it to `true`. **Idempotency.** `POST` accepts an `Idempotency-Key` header. The first request with a given key is performed and its response kept for 24 hours; an identical retry returns that same response with `Idempotent-Replay: true` rather than creating a second resource. The record covers the request body too, so reusing a key with different content is a new request, not a replay. `PATCH` and `DELETE` are keyed on a resource id and need no header. **Audit and undo.** Every applied write records what changed, who changed it and the state it replaced, in the same transaction as the change. `GET /audit` lists those entries and `POST /audit/{auditId}/undo` puts the resource back. Undo refuses rather than guessing: it will not reverse a create (call `DELETE`, which previews and audits like any other write), will not run twice on one entry, and will not restore over a resource that has since been deleted or re-created. **Rate limit.** Mutations spend a separate, tighter budget than reads: 20 per minute per key, including dry runs. paths: /metrics/catalog: get: tags: - Attribution and revenue summary: List queryable metrics description: >- Discover every metric id `POST /metrics` accepts, with its unit, category and availability. A metric with `supported: false` resolves but never queries a source: it returns an explicit `unavailableReason` instead of a number. Cached for five minutes. operationId: list-metrics responses: '200': $ref: '#/components/responses/MetricsCatalog' '503': $ref: '#/components/responses/Error' components: responses: MetricsCatalog: description: Successful response. content: application/json: schema: $ref: '#/components/schemas/MetricsCatalogResponse' Error: description: Error response. content: application/json: schema: type: object properties: error: type: string schemas: MetricsCatalogResponse: type: object additionalProperties: true required: - metrics - total - complete properties: metrics: type: array items: $ref: '#/components/schemas/MetricsCatalogMetric' total: type: integer custom_metric_prefix: type: string description: >- Prefix for per-workspace event metrics (`custom:`). These are unbounded and therefore not listed; discover event names from `/event-names`. id_aliases: type: object additionalProperties: type: string description: >- Stale id to canonical id. Stale ids resolve, but prefer the canonical one. complete: type: boolean MetricsCatalogMetric: type: object additionalProperties: true required: - id - label - platform - unit - supported properties: id: type: string description: The id to pass in `metric_ids`. label: type: string platform: type: string enum: - datalyr - shopify - stripe - revenuecat - skan - superwall - whop - meta - google - tiktok platform_label: type: string unit: type: string enum: - number - currency - percentage description: '`currency` values are USD.' category: type: string description: >- Cross-platform grouping: Standard, Conversion, Profitability, SaaS & Mobile, or Custom. aggregation: type: string enum: - sum - max - avg - derived decimals: type: - integer - 'null' supported: type: boolean description: >- `false` means the id resolves but its historical formula is not certified. Querying it returns an explicit `unavailableReason`, never a number. unavailable_reason: type: - string - 'null' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Datalyr Agent key (dk_agent_…) ````