> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.omni.co/feedback
```json
{
"path": "/api/queries/wait-for-query-results",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Wait for query results
> Polls for the results of one or more query jobs. Use this endpoint when a request to the [Run query endpoint](/api/queries/run-query) times out and returns `remaining_job_ids` in the response.
This endpoint will wait for the specified jobs to complete and return their results. If the jobs are still processing when the request times out, the response will include the remaining job IDs to poll again.
## OpenAPI
````yaml /api/openapi.yaml get /v1/query/wait
openapi: 3.1.0
info:
title: Omni API
description: >
The Omni REST API provides programmatic access to your Omni instance for
managing users, documents, queries, schedules, and more.
version: 1.0.0
contact:
name: Omni Support
url: https://docs.omni.co
servers:
- url: https://{instance}.omniapp.co/api
description: Production
variables:
instance:
default: blobsrus
description: Your production Omni instance subdomain
- url: https://{instance}.playground.exploreomni.dev/api
description: Playground
variables:
instance:
default: blobsrus
description: Your playground Omni instance subdomain
security:
- bearerAuth: []
- orgApiKey: []
tags:
- name: AI
description: AI-powered query generation
- name: API Tokens
description: >-
Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
grants)
- name: Connections
description: Manage database connections
- name: Connection environments
description: Manage connection environments database connections
- name: Content
description: Unified content retrieval (documents and folders)
- name: Content migration
description: Export and import dashboards
- name: Content validator
description: Validate content against models and perform find/replace operations
- name: Dashboard downloads
description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
- name: Dashboard filters and controls
description: Read and update dashboard filter and control default values
- name: dbt
description: Manage dbt configuration for connections
- name: Documents
description: Create, retrieve, and manage documents
- name: Document favorites
description: Favorite and unfavorite documents
- name: Document labels
description: Apply and manage labels on documents
- name: Document permissions
description: Manage document-level access
- name: Labels
description: >
Manage labels in an organization. Labels can be applied to documents and
folders to help organize and categorize content.
**Label types:**
- **Basic labels**: Can be created and managed by any user
- **Verified labels**: Indicate curated or officially sanctioned content.
Admin-only.
- **Homepage labels**: Appear on the organization homepage. Admin-only.
- name: Folders
description: Create and organize content folders
- name: Folder permissions
description: Manage folder-level access
- name: Jobs
description: Check status of asynchronous jobs
- name: Models
description: Create and manage data models
- name: Model branches
description: Manage model branches and merge changes
- name: Model git configuration
description: Manage git configuration for shared models
- name: Queries
description: Execute workbook queries
- name: Schedules
description: Create and manage scheduled tasks
- name: Schedule recipients
description: Manage schedule recipients
- name: Schema refresh schedules
description: Manage automated schema refresh schedules for connections
- name: Topics
description: Retrieve topic information from models
- name: Uploads
description: Manage file uploads
- name: Users
description: Manage users
- name: User attributes
description: Manage user attribute definitions
- name: User groups
description: Manage user groups
- name: User model roles
description: Manage model and connection role assignments for users
- name: User group model roles
description: Manage model and connection role assignments for user groups
- name: Uploads
description: Manage CSV and spreadsheet uploads
paths:
/v1/query/wait:
get:
tags:
- Queries
summary: Wait for query results
description: >
Polls for the results of one or more query jobs. Use this endpoint when
a request to the [Run query endpoint](/api/queries/run-query) times out
and returns `remaining_job_ids` in the response.
This endpoint will wait for the specified jobs to complete and return
their results. If the jobs are still processing when the request times
out, the response will include the remaining job IDs to poll again.
operationId: waitForQuery
parameters:
- name: job_ids
in: query
required: true
schema:
type: array
items:
type: string
format: uuid
description: >
An array of job IDs to poll for results. These IDs are returned in
the `remaining_job_ids` property when a request to the [Run query
endpoint](/api/queries/run-query) times out.
Format the parameter as a JSON array (e.g.,
`?job_ids=["job-id-1","job-id-2"]`).
responses:
'200':
description: >
Successful response containing the query results for completed jobs.
If all jobs have completed, `timed_out` will be `false` and the
response will include the full query results.
If some jobs are still processing when this request times out,
`timed_out` will be `true` and `remaining_job_ids` will contain the
IDs of jobs that are still running. Continue polling with these IDs
until all jobs complete.
content:
application/json:
schema:
type: object
properties:
job_id:
type: string
format: uuid
description: The unique identifier for the query job
status:
type: string
description: Job status (e.g., `COMPLETE`, `PLANNED`)
client_result_id:
type: string
format: uuid
description: Client-side result identifier
summary:
type: object
description: >-
Query execution summary including SQL, stats, and field
metadata
cache_metadata:
type: object
description: Cache information including TTL and data freshness
query:
type: object
description: The executed query details
result:
type: string
description: Base64 encoded Apache Arrow table containing query results
stream_stats:
type: object
description: Server-side streaming metrics
properties:
server_stream:
description: >-
Time in milliseconds to stream the result data from
the server
type: integer
remaining_job_ids:
type: array
items:
type: string
format: uuid
description: >-
IDs of jobs still processing if this request timed out.
Continue polling with these IDs.
timed_out:
type: boolean
description: >-
Indicates if the request timed out. If `true`, use
`remaining_job_ids` to poll again.
examples:
completedJob:
summary: Job completed successfully
value:
job_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
status: COMPLETE
client_result_id: b2c3d4e5-f6a7-8901-bcde-f12345678901
summary:
sql: SELECT * FROM order_items LIMIT 10
total_rows: 10
execution_time_ms: 245
result: QVJST1cxAAD/////...
timed_out: false
timedOut:
summary: Request timed out with remaining jobs
value:
timed_out: true
remaining_job_ids:
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
- b2c3d4e5-f6a7-8901-bcde-f12345678901
'400':
description: |
Bad Request. Possible causes:
- Missing or invalid `job_ids` parameter
- `job_ids` is not a valid JSON array
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missingJobIds:
summary: Missing job_ids parameter
value:
detail: job_ids parameter is required
status: 400
invalidJobIds:
summary: Invalid job_ids format
value:
detail: job_ids must be a valid JSON array of UUIDs
status: 400
'401':
description: Missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: |
Not Found. Possible causes:
- One or more job IDs do not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
jobNotFound:
summary: Job not found
value:
detail: Job with id does not exist
status: 404
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- bearerAuth: []
components:
schemas:
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example:
message:
type: string
description: Detailed error description
example:
responses:
TooManyRequests:
description: Too Many Requests - Rate limit exceeded (60 requests/minute)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Can be either an [Organization API
Key](/api/authentication#organization-api-keys) or [Personal Access
Token (PAT)](/api/authentication#personal-access-tokens-pat).
Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
orgApiKey:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Requires an [Organization API
Key](/api/authentication#organization-api-keys). Personal Access Tokens
(PATs) are not supported for this endpoint.
Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`
````