Conventions and errors | ATX AnalyticsTable Docs

Conventions and errorsCursor paging, JSON, CSV and NDJSON, rate limits, Idempotency-Key, load shedding, request ids, and every error code with whether to retry it. Results come in pages of up to 50,000 rows (1,000 by default). Each page carries a nextCursor: send the same request with that cursor to get the next page, and a null cursor means the last page. A cursor belongs to its query and is refused for any other. Add ?format=csv or ?format=ndjson (or the matching Accept header) for CSV or one JSON object per line. CSV cells that a spreadsheet would run as a formula are neutralised. Each credential has a rate limit of 600 requests a minute with a burst of 100, reported in RateLimit-* headers, and is answered 429 with Retry-After when exceeded.

Paging, formats, limits and errors

Results come in pages of up to 50,000 rows (1,000 by default). Each page carries a nextCursor: send the same request with that cursor to get the next page, and a null cursor means the last page. A cursor belongs to its query and is refused for any other. Add ?format=csv or ?format=ndjson (or the matching Accept header) for CSV or one JSON object per line. CSV cells that a spreadsheet would run as a formula are neutralised. Each credential has a rate limit of 600 requests a minute with a burst of 100, reported in RateLimit-* headers, and is answered 429 with Retry-After when exceeded.
An Idempotency-Key header makes a retried POST return the first answer instead of running again. Every error is an RFC 9457 problem document with a stable code, such as read_only_sql, rate_limited, planner_error or unavailable, and a retryable flag. A client should retry only when that flag is true, waiting as long as Retry-After says.

Paging

A response carries nextCursor, also sent as the ATX-Next-Cursor header. To read the next page, send the same body plus "cursor". null means the last page. A cursor is tied to the statement, the project and the page size: replayed against a different query it is refused with 400 bad_request, and never returns another query's rows. The largest limit is 50,000 rows a page.

Formats

JSON — nothing (the default) — { columns, rows, rowCount, nextCursor, durationMs }
CSV — ?format=csv or Accept: text/csv — RFC 4180 CSV with a header row. Cells a spreadsheet would run as a formula (starting =, +, - or @) are neutralised.
NDJSON — ?format=ndjson or Accept: application/x-ndjson — One JSON object per line — easy to stream into another tool

Rate limits

Each credential has a token bucket: by default 600 requests a minute with a burst of 100 (ANALYTICS_API_RATE_PER_MIN and ANALYTICS_API_BURST). Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy. An empty bucket answers 429 rate_limited with Retry-After. Callers sharing the installation token are bucketed by 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, marked Idempotent-Replayed: true, and the call does not run again — an MCP tool is not called twice, a remote system is not queried twice. The same key with a different body answers 422 idempotency_mismatch; a retry while the first call is still running answers 409 conflict. 5xx, 429 and 409 answers are not remembered, so retrying them really retries.

Load, time limits and tracing

Queries go through the application's admission lanes. Under load the API answers 503 unavailable with Retry-After rather than queueing without end.
A query that runs past the installation's time limit is stopped. A result larger than the result-size limit answers 413 payload_too_large: ask for fewer rows a page.
A client that disconnects cancels its query; the server records 499 client_closed.
Send X-Request-Id and the server echoes it; without one, the server makes one. The id appears in problem documents and in the audit trail, so a failing call can be found in the server log.
Cache-Control: no-store is set on every response, because data and permissions change.

Errors

Every error is an application/problem+json document (RFC 9457). Decide whether to retry from retryable, not from the HTTP status alone.
{ "type": "https://atxinstitute.com/docs/api/errors#read_only_sql", "title": "Only read-only SQL is accepted", "status": 422, "detail": "The public API runs read-only queries only. Run one statement at a time.", "instance": "/api/v1/query", "code": "read_only_sql", "requestId": "6f1c2e0a-...", "retryable": false }
bad_request — 400 — no — A missing sql, a bad cursor or limit, an unknown metric. field names the culprit.
unauthorized — 401 — no — No credential, or a wrong one
forbidden — 403 / 402 — no — The role or an 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
conflict — 409 — yes — The same Idempotency-Key is still running; a stale MCP configuration edit
idempotency_mismatch — 422 — no — An Idempotency-Key reused with a different body
read_only_sql — 422 — no — A write, several statements, or file or 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, an 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; 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 — An administrator turned the feature off
A refusal from a layer that predates v1 — sign-in, roles, the licence gate, the body parser — is converted to a problem document too, with the original reason in reason.
A retry loop that does it properly:
import time, uuid def call(method, path, **kw): for attempt in range(5): r = S.request(method, BASE + path, timeout=120, **kw) if r.ok: return r problem = r.json() if r.headers.get("content-type", "").startswith("application/problem+json") else {} if not problem.get("retryable") or attempt == 4: raise RuntimeError(f"{r.status_code} {problem.get('code')}: {problem.get('detail')}") time.sleep(int(r.headers.get("Retry-After", 2 ** attempt))) # A side-effecting POST: make the retry safe call("POST", "/mcp/servers/jira/tools/searchJiraIssuesUsingJql/call", json={"arguments": {"jql": "project = FIN"}}, headers={"Idempotency-Key": str(uuid.uuid4())})

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.