ATX AnalyticsTable REST API | Authentication, Paging, Rate Limits, Errors

REST API — getting startedAuthenticate, page through results, retry safely and read every error the API can return. Everything a client needs before its first call: which credential to use and which role it carries, how paging, formats, rate limits, idempotency and request ids work, what every error code means, and how an administrator operates the API. Examples use three shell variables — the installation's URL, a scoped service token and a project path.

Quick start

GET /api/v1/me tells a client which identity, role and rate limit it has — the first call to make with a new credential.

Authentication

The API takes the same credentials as the rest of the backend:

The installation token acts as admin. Give every integration its own scoped service token, with the lowest role that does the job, so that it can be revoked on its own and is named in the audit trail.

Scoped service tokens (recommended for integrations). An administrator lists tokens in the file named by ANALYTICS_API_TOKENS_FILE, each with its own name and role. The file holds only SHA-256 digests. Revoking a token is an edit of the file, and no restart is needed. Send the token as Authorization: Bearer <token>; the audit trail records the call as service:<name>.
Microsoft Entra ID access tokens, where the installation signs users in with Entra ID. The call runs as that person, with the role their groups map to.
The installation token in X-Analytics-Token. It acts as admin. Use it only for break-glass administration, never in an integration.

Roles

The table is enforced by the backend's role classifier, and a test asserts that it agrees with the API catalogue. Row- and column-level security and object-level grants apply to API calls exactly as they do in the application.

Discovery (/api/v1, /openapi.json, /docs, /me, /health) — viewer
Tables, POST /query, connections, connection query — viewer (object grants apply)
Metrics catalogue and POST /metrics/query — viewer (the grant on the metric's connection applies)
Dashboards and widget data — viewer (the dashboard grant applies)
MCP: list servers, templates, tools — viewer
MCP: call a tool — analyst

Paging and cursors

Responses carry nextCursor (also sent as the ATX-Next-Cursor header). Send the same body plus "cursor". null means the last page. The maximum limit is 50 000; the default is 1 000.

A cursor is tied to the statement, the project and the page size. Replaying it against a different query returns 400 bad_request and never returns another query's rows.

Formats

JSON is the default.
CSV: ?format=csv or Accept: text/csv returns RFC 4180 CSV with a header row. Cells that a spreadsheet would execute as a formula (=, +, -, @) are neutralised.
NDJSON: ?format=ndjson or Accept: application/x-ndjson returns one JSON object per line.

Rate limits

Each credential has a token bucket — 600 requests a minute with a burst of 100 by default, configured with ANALYTICS_API_RATE_PER_MIN and ANALYTICS_API_BURST. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy. When the bucket is empty, the answer is 429 rate_limited with Retry-After.

Callers that share the installation token are bucketed per IP address, so one script cannot starve the others.

Idempotency

On a POST, send Idempotency-Key: <uuid>. A retry with the same key and the same body within 24 hours gets the first answer back with Idempotent-Replayed: true, and the call does not run again.

The same key with a different body returns 422 idempotency_mismatch.
A retry while the first call is still running returns 409 conflict.
5xx, 429 and 409 answers are not remembered, so retrying them really retries.

Load shedding and limits

Queries use the application's admission lanes. Under load the API answers 503 unavailable with Retry-After. A query that exceeds the installation's time limit is stopped. A result that exceeds the result-size limit returns 413 payload_too_large: ask for fewer rows per page.

Request ids, caching and versioning

Tracing. Send X-Request-Id and the server echoes it. If you don't send one, the server generates one. The id appears in problem documents and in the audit trail.
Caching. Cache-Control: no-store is set on every response, because data and permissions change.
Versioning. v1 changes only additively — new endpoints and new optional fields may appear in any release, so clients should ignore fields they do not know. Breaking changes go to /api/v2, which would run alongside v1 for at least two releases. Every response carries ATX-API-Version: 1.

Errors

Errors use the application/problem+json content type (RFC 9457). code is the stable, machine-readable part; title and detail are prose. Decide whether to retry from retryable, and wait for Retry-After when it is present.

A refusal from a layer that does not know about v1 — access control, RBAC, the licence gate, the body parser — is still converted to a problem document, with the original reason in reason.

bad_request — 400 — no — Missing sql, a bad cursor, a bad limit, an unknown metric. field names the culprit.
unauthorized — 401 — no — No credential, or a wrong one.
forbidden — 403 / 402 — no — The role or object grant does not allow this; 402 when the licence lacks the connector.
not_found — 404 — no — Unknown table, connection, metric, dashboard, server or endpoint.
method_not_allowed — 405 — no — The endpoint does not accept this HTTP method.
conflict — 409 — yes — The same Idempotency-Key is still in flight; a stale MCP configuration edit.
idempotency_mismatch — 422 — no — The Idempotency-Key was reused with a different body.
read_only_sql — 422 — no — A write, several statements, or file/URL access.
planner_error — 422 — no — The semantic planner cannot join the requested objects, or a parameter is invalid.
query_error — 422 — no — The database rejected the SQL (syntax, unknown column).
payload_too_large — 413 — no — The result is bigger than the server allows; page smaller.
rate_limited — 429 — yes — Over the credential's rate; honour Retry-After.
client_closed — 499 — yes — The client disconnected; the query was cancelled.
internal — 500 — yes — An unexpected fault. The detail is generic on purpose, and the server log has the request id.
upstream_error — 502 — yes — An MCP server or remote database failed.
unavailable — 503 / 507 — yes — Busy, draining, a circuit is open, or the database is full (507).
upstream_timeout — 504 — yes — An MCP server missed its deadline.
disabled — 503 — no — The administrator turned the feature off.

Python — with retries done properly

Operating the API

ANALYTICS_PUBLIC_API=0 — on — Turns /api/v1 off. Every call returns 503 disabled.
ANALYTICS_API_TOKENS_FILE — — — Scoped service tokens (see Authentication)
ANALYTICS_API_RATE_PER_MIN — 600 — Rate per credential
ANALYTICS_API_BURST — 100 — Bucket size
Runtime limits (query time limit, result size, admission lanes) — as configured — Apply to API queries exactly as to the application's own
Network exposure. On a server installation, publish the backend only through your reverse proxy (TLS, WAF). The API adds no new listener and no new port.
Audit. Every call is recorded by the global audit middleware. Queries also add a query.run record (connection, kind, SHA-256 of the SQL, row count, duration, outcome), and MCP calls add mcp.tool.call records. Neither record ever holds data.
Monitoring. /metrics (Prometheus) includes analytics_http_requests_total{route="/api/v1/…"}, the admission series, and analytics_mcp_* for MCP servers. GET /api/v1/health is suitable for a synthetic check from an API gateway.

Glossary terms on this page

KPI dashboard: definition

ATX Institute on LinkedIn

This site needs JavaScript for the full experience. Every page above is reachable without it.