Wait for query results
Poll for the results of one or more query jobs. Use this endpoint when a request to the Run query endpoint times out and returns remaining_job_ids in the response.
This endpoint waits for the specified jobs to complete and returns their results as a stream of newline-delimited JSON: one line per completed job, followed by a footer line.
If the footer’s remaining_job_ids is not empty, call this endpoint again with those IDs until the list is empty and timed_out is "false".
Authorizations
Can be either an Organization API Key or Personal Access Token (PAT).
Include in the Authorization header as: Bearer YOUR_TOKEN
Query Parameters
If "true", completed job lines omit result; read the data afterward with the Read query results by offset endpoint. See Reading large results for more information.
true, false Required unless the deprecated job_ids parameter is sent. A comma-separated list of job UUIDs to poll for results. These IDs are returned in the remaining_job_ids property when a request to the Run query endpoint times out.
For example, ?jobIds=a1b2c3d4-e5f6-7890-abcd-ef1234567890,b2c3d4e5-f6a7-8901-bcde-f12345678901. A value that is not a valid UUID returns a 400 error.
"a1b2c3d4-e5f6-7890-abcd-ef1234567890,b2c3d4e5-f6a7-8901-bcde-f12345678901"
Deprecated: Use jobIds instead.
Response
Query results for completed jobs, streamed as newline-delimited JSON (text/ndjson): one object per line. The response as a whole cannot be parsed as a single JSON document — parse it line by line.
The stream ends with a footer line. If the footer's remaining_job_ids is not empty, continue polling this endpoint with those IDs until the list is empty.
- Option 1
- Option 2
One line of the Wait for query results NDJSON stream — one line per completed job, 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.

