> ## 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. # Read query results by offset > Read a completed job's stored result by raw byte offset. See [Reading large results](/api/queries/run-query#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. ## OpenAPI ````yaml /api/openapi.yaml get /v1/query/results 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: Who Am I description: Inspect your own user permissions - name: AI description: AI-powered query generation - name: AI Credit Controls description: Manage organization-level AI credit usage - name: AI Credit Usage description: Monitor AI credit usage - name: AI Evals description: >- Manage prompt sets and runs used to score AI quality against curated prompt suites. - name: AI Model Suggestions description: Manage AI-generated suggestions for shared models - name: AI Routines description: >- Manage Routines, which are scheduled, recurring AI-powered tasks that run automatically on your data - name: Apps description: Draft and publish app documents. - name: Documents v2 description: > A draft-based workflow for creating and editing documents: create a document, patch a draft, then publish. - name: Documents description: Create, retrieve, and manage documents - name: API Tokens description: >- Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth grants) - name: IP Allowlist description: Manage the organization's IP allowlist - name: Connections description: Manage database connections - name: Connection environments description: Manage connection environments database connections - name: Color Palettes description: Manage custom chart color palettes - 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: 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: Embed description: Manage embed sessions - name: Labels description: | Manage labels in the organization - name: Folders description: Create and organize content folders - name: Folder labels description: Apply and manage labels on 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: Skills description: >- Manage skills, the saved slash-command instructions the Omni AI assistant runs - 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/results: get: tags: - Queries summary: Read query results by offset description: > Read a completed job's stored result by raw byte offset. See [Reading large results](/api/queries/run-query#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. operationId: readQueryResults parameters: - name: jobId in: query required: true schema: type: string format: uuid example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 description: > ID of a completed query job, from the [Run query](/api/queries/run-query) or [Wait for query results](/api/queries/wait-for-query-results) response. Only one job can be read per request. - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 description: > Raw result byte to start reading from: `0`, or the previous response's `stream_stats.next_offset`. - name: maxBytes in: query required: false schema: type: integer exclusiveMinimum: 0 example: 50000000 description: > Most raw result bytes to return. Omit to read to the end of the result. - name: timeoutMs in: query required: false schema: type: integer exclusiveMinimum: 0 example: 60000 description: > 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. responses: '200': description: > 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. content: text/ndjson: schema: description: >- One job line including the requested slice in `result` and the byte window in `stream_stats`, then a footer line. anyOf: - $ref: '#/components/schemas/QueryStreamJobLine' - $ref: '#/components/schemas/QueryStreamFooterLine' examples: jobLine: summary: Job line for a paged read value: job_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: COMPLETE result: QVJST1cxAAD/////... stream_stats: offset: 0 bytes: 25000000 total_bytes: 60000000 next_offset: 25000000 '400': description: | Bad Request. Possible causes: - `jobId` is missing or not a valid UUID - `offset` is negative or not an integer - `maxBytes` or `timeoutMs` is zero, negative, or not an integer content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidOffset: summary: Negative offset value: detail: 'Bad Request: offset: Too small: expected number to be >=0' status: 400 '401': description: Missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/ApiError401' '429': $ref: '#/components/responses/TooManyRequests' '500': description: Error reading query results content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: QueryStreamJobLine: type: object required: - job_id - status description: > Per-job line emitted as each job reaches a terminal state. A completed job includes the result set as base64-encoded Arrow IPC in `result`; a failed job carries `error_type` and `error_message` instead. properties: cache_metadata: description: > Cache metadata for the result, including row count, byte size, freshness timestamps, requery plan key. client_result_id: type: string description: >- Client-supplied result ID echoed back for correlating jobs to queries. column_name_mapping: type: object additionalProperties: type: string error: description: >- Structured error details, e.g. an OAuth re-authentication requirement. error_message: type: string description: Human-readable error message. Present on failed jobs. example: No such view "order_items" error_type: type: string description: > Machine-readable error category (e.g. `PLAN`, `SQL`). Present on failed jobs. example: PLAN job_id: type: string description: ID of the query job this line reports on. kill_reason: type: string description: Why the job was terminiated, when it was cancelled. query: description: The query that was executed. requery_fallback_sql: type: string requery_sql: type: string description: >- SQL to re-query the cached result set, when the result supports requery. requery_table_name: type: string result: type: string description: > 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. status: type: string description: > Job status. Values include `COMPLETE`, `ERROR`, `FAILED`, and `MISSING`. example: COMPLETE stream_stats: type: object additionalProperties: {} description: > 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](/api/queries/read-query-results-by-offset) endpoint: decode each `result` and append the bytes before parsing the Arrow stream. properties: bytes: type: integer description: >- Raw result bytes in this response (the decoded length of `result`). next_offset: oneOf: - type: integer - type: 'null' description: > The offset to pass to the results endpoint for the next read, or `null` once this response reached the end of the result. offset: type: integer description: > Raw result byte this response starts at: `0`, except on a results read with an offset. server_stream: type: number description: Milliseconds the server spent streaming the result. total_bytes: type: integer description: Size of the whole stored result, in raw bytes. summary: description: > 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: type: object additionalProperties: type: string QueryStreamFooterLine: type: object required: - remaining_job_ids - timed_out description: Last line of the stream. properties: remaining_job_ids: type: array items: type: string description: > Job IDs that had not completed when the wait window elapsed. Poll the [Wait for query results](/api/queries/wait-for-query-results) endpoint with these IDs until the list is empty. example: [] timed_out: type: string enum: - 'false' - 'true' description: > Whether the wait window elapsed before every job completed. This is a string value (ex: `"true"`), not a boolean (`true`). example: 'false' Error: type: object properties: error: type: string description: HTTP response code for the error example: message: type: string description: Detailed error description example: ApiError401: type: object properties: detail: type: string description: Human-readable error message describing what went wrong. example: 'Unauthorized: Missing or invalid API key' status: type: integer description: HTTP status code of the error. example: 401 required: - detail - status 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#token-types). 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` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.