Results

Retrieve persisted query results. Every query execution persists its results asynchronously. Results transition through statuses: processing → ready (or failed). Once ready, the full result data can be retrieved by ID.

List results

List stored results for the database named by the required X-Database-Id header.

Query parameters

• limit integer — Maximum number of results (default: 100, max: 1000)
• offset integer — Pagination offset (default: 0)

Headers

• X-Database-Id string — required. Database to scope the results to (required)

Response 200 — List of results

• count integer — required. Number of results returned in this response. Min: 0
• has_more boolean — required. Whether there are more results available after this page
• limit integer — required. Limit used for this request. Min: 0
• offset integer — required. Pagination offset used for this request. Min: 0
• results ResultInfo[] — required
  • created_at string — required
  • error_message string,null
  • id string — required
  • status string — required

{
  "count": 0,
  "has_more": true,
  "limit": 0,
  "offset": 0,
  "results": [
    {
      "created_at": "2026-01-01T00:00:00Z",
      "error_message": "string",
      "id": "string",
      "status": "string"
    }
  ]
}

Errors

Get result

Retrieve a persisted query result by ID. The response format for the ready state is selected by Accept header or ?format= query param; non-ready states use the same status codes and JSON body shape regardless of format.

?format= accepts arrow, json, csv, md, parquet and takes precedence over Accept. markdown is accepted as a runtime alias for md. Use ?offset=N&limit=M to slice the result; offset defaults to 0 and limit is unbounded by default. Both must be non-negative; invalid values return 400. When a finite limit doesn't reach the end of the result, a Link header with rel="next" points at the following page. ?offset/?limit are ignored for format=parquet since that path returns the underlying file unchanged.

Ready responses (Arrow, CSV, Markdown, JSON) carry X-Total-Row-Count (the full result row count, independent of offset/limit). Responses are streamed end-to-end, so a client can disconnect at any time and the server stops reading.

IEEE special floats (±Inf, NaN) have no canonical JSON representation. For cross-format consistency the JSON, CSV, and Markdown paths emit them as null / empty cells, and JSON nullable[] is widened to match. The Arrow IPC and Parquet bodies are binary round-trip formats and preserve the raw IEEE values; callers cross-checking a result across CSV and Parquet should not byte-compare those slots.

Path parameters

• id string — required. Result ID

Query parameters

• offset integer — Rows to skip (default: 0)
• limit integer — Maximum rows to return (default: unbounded)
• format ResultsFormatQuery — arrow, json, csv, md, or parquet — overrides the Accept header. markdown is also accepted at runtime as an alias for md.

Headers

• X-Database-Id string — required. Database the result belongs to (required)

Response 200 — Result data. The body depends on the negotiated format: JSON callers receive GetResultResponse; Arrow callers receive an Arrow IPC stream; CSV callers receive comma-separated text (LF-terminated, double-quote escaped, RFC 4180-style quoting but not RFC 4180-strict on line endings); Markdown callers receive a single GitHub-flavored pipe table; Parquet callers receive the raw parquet bytes, served as-is. Non-finite floats (±Inf, NaN) render as null (JSON) or empty cells (CSV, Markdown) for cross-format consistency. Accept is treated as a flat content-type list — q= quality values are ignored; use ?format= to disambiguate.

• columns string[] | null
• error_message string,null
• nullable boolean[] | null
• result_id string — required
• row_count integer,null
• rows any[][] | null — Array of rows, where each row is an array of column values.
• status string — required

{
  "columns": [
    "string"
  ],
  "error_message": "string",
  "nullable": [
    true
  ],
  "result_id": "string",
  "row_count": 0,
  "rows": [
    [
      null
    ]
  ],
  "status": "string"
}

Response 202 — Result is still being computed (pending or processing). Poll the same URL.

• columns string[] | null
• error_message string,null
• nullable boolean[] | null
• result_id string — required
• row_count integer,null
• rows any[][] | null — Array of rows, where each row is an array of column values.
• status string — required

{
  "columns": [
    "string"
  ],
  "error_message": "string",
  "nullable": [
    true
  ],
  "result_id": "string",
  "row_count": 0,
  "rows": [
    [
      null
    ]
  ],
  "status": "string"
}

Errors