Skip to main content
GET
Read query results by offset

Authorizations

Authorization
string
header
required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Query Parameters

jobId
string<uuid>
required

ID of a completed query job, from the Run query or Wait for query results response. Only one job can be read per request.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

offset
integer
default:0

Raw result byte to start reading from: 0, or the previous response's stream_stats.next_offset.

Required range: x >= 0
maxBytes
integer

Most raw result bytes to return. Omit to read to the end of the result.

Example:

50000000

timeoutMs
integer

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.

Example:

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.

One job line including the requested slice in result and the byte window in stream_stats, then a footer line.

job_id
string
required

ID of the query job this line reports on.

status
string
required

Job status. Values include COMPLETE, ERROR, FAILED, and MISSING.

Example:

"COMPLETE"

cache_metadata
any

Cache metadata for the result, including row count, byte size, freshness timestamps, requery plan key.

client_result_id
string

Client-supplied result ID echoed back for correlating jobs to queries.

column_name_mapping
object
error
any

Structured error details, e.g. an OAuth re-authentication requirement.

error_message
string

Human-readable error message. Present on failed jobs.

Example:

"No such view \"order_items\""

error_type
string

Machine-readable error category (e.g. PLAN, SQL). Present on failed jobs.

Example:

"PLAN"

kill_reason
string

Why the job was terminiated, when it was cancelled.

query
any

The query that was executed.

requery_fallback_sql
string
requery_sql
string

SQL to re-query the cached result set, when the result supports requery.

requery_table_name
string
result
string

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.

stream_stats
object

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.

summary
any

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.

used_keys
object