Read query results by offset
Read a completed job’s stored result by raw byte offset. See Reading large results for the full flow with completionOnly.
Results stay readable for about an hour after the job completes. Reading a job that hasn’t completed yet, or whose result has expired, returns an error status on the job line.
Authorizations
Can be either an Organization API Key or Personal Access Token (PAT).
Include in the Authorization header as: Bearer YOUR_TOKEN
Query Parameters
ID of a completed query job, from the Run query or Wait for query results response. Only one job can be read per request.
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Raw result byte to start reading from: 0, or the previous response's stream_stats.next_offset.
x >= 0Most raw result bytes to return. Omit to read to the end of the result.
50000000
Stop streaming after roughly this many milliseconds; stream_stats.next_offset says where to resume. At least one chunk is always returned, so a slow read can't stall at the same offset.
60000
Response
The requested byte window of the job's result, streamed as newline-delimited JSON (text/ndjson): one job line, then a footer line. The response as a whole cannot be parsed as a single JSON document — parse it line by line.
- Option 1
- Option 2
One job line including the requested slice in result and the byte window in stream_stats, then a footer line.
ID of the query job this line reports on.
Job status. Values include COMPLETE, ERROR, FAILED, and MISSING.
"COMPLETE"
Cache metadata for the result, including row count, byte size, freshness timestamps, requery plan key.
Client-supplied result ID echoed back for correlating jobs to queries.
Structured error details, e.g. an OAuth re-authentication requirement.
Human-readable error message. Present on failed jobs.
"No such view \"order_items\""
Machine-readable error category (e.g. PLAN, SQL). Present on failed jobs.
"PLAN"
Why the job was terminiated, when it was cancelled.
The query that was executed.
SQL to re-query the cached result set, when the result supports requery.
Result rows as a base64-encoded Arrow IPC stream. Present on completed jobs. Decode with any Arrow IPC reader and use summary.fields to interpret the columns.
Streaming stats for a completed job, including the byte window its result covers. A large result can be read in pieces with the Read query results by offset endpoint: decode each result and append the bytes before parsing the Arrow stream.
Execution summary. summary.fields maps field names to their metadata and is needed to interpret the decoded Arrow table; also carries the generated SQL and cache type.

