> ## 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/ai/get-ai-job-status",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Get AI job status
> Retrieve the current status and details of an AI job, including its state, progress information, and result summary.
The response fields vary by `state` — for example, `progress` is only present during `EXECUTING`, and `resultSummary` is only present when `COMPLETE`.
Poll this endpoint every 2–5 seconds until the job reaches a terminal state (`COMPLETE`, `FAILED`, or `CANCELLED`).
## OpenAPI
````yaml /api/openapi.yaml get /v1/ai/jobs/{jobId}
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/ai/jobs/{jobId}:
get:
tags:
- AI
summary: Get AI job status
description: >
Retrieve the current status and details of an AI job, including its
state, progress information, and result summary.
The response fields vary by `state` — for example, `progress` is only
present during `EXECUTING`, and `resultSummary` is only present when
`COMPLETE`.
Poll this endpoint every 2–5 seconds until the job reaches a terminal
state (`COMPLETE`, `FAILED`, or `CANCELLED`).
operationId: getAIJobStatus
parameters:
- name: jobId
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the AI job
responses:
'200':
description: Job status retrieved successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
description: The unique identifier for this job.
example: 550e8400-e29b-41d4-a716-446655440000
state:
type: string
enum:
- CANCELLED
- COMPLETE
- DELIVERING
- EXECUTING
- FAILED
- QUEUED
description: >-
Current state of the job. Terminal states are `COMPLETE`,
`FAILED`, and `CANCELLED`. Poll until the job reaches a
terminal state.
example: QUEUED
prompt:
type: string
description: The natural language prompt that was submitted.
example: What are the top 5 products by revenue?
conversationId:
type: string
format: uuid
description: >-
The conversation this job is associated with. Use this to
submit follow-up jobs in the same conversation thread.
example: 660e8400-e29b-41d4-a716-446655440001
modelId:
type: string
format: uuid
nullable: true
description: The shared model ID used for query generation.
example: 770e8400-e29b-41d4-a716-446655440002
branchId:
type: string
format: uuid
nullable: true
description: >-
Branch ID used for model context, or null if querying the
main shared model.
organizationId:
type: string
format: uuid
description: The organization that owns this job.
example: 880e8400-e29b-41d4-a716-446655440003
userId:
type: string
format: uuid
description: The user ID who created (or is associated with) this job.
example: 990e8400-e29b-41d4-a716-446655440004
topicName:
type: string
nullable: true
description: >-
Topic name used to scope query generation, or null if the
AI selected the topic automatically.
example: order_items
omniChatUrl:
type: string
format: uri
description: >-
URL to view this conversation in the Omni chat interface.
Opens the chat session where the job actions and results
are visible.
example: >-
https://blobsrus.omni.co/chat/660e8400-e29b-41d4-a716-446655440001
progress:
type: object
nullable: true
description: >
**Only present in `EXECUTING` state.** Real-time progress
information. Null if no progress has been reported yet.
Updated in real-time as the AI works through iterations.
properties:
iteration:
type: integer
description: >-
Current iteration number. The AI may take multiple
iterations to refine queries and generate a complete
answer.
example: 2
message:
type: string
description: >-
Human-readable status message describing what the AI
is currently doing.
example: 'Running query: Top products by revenue'
updatedAt:
type: string
format: date-time
description: When this progress update was recorded.
example: '2025-01-15T10:00:08.000Z'
required:
- iteration
- message
- updatedAt
resultSummary:
type: string
description: >
**Only present in COMPLETE state.** Markdown-formatted
summary of the job result. For the full result with query
details and data, use the [Stream AI job results
endpoint](/api/ai/stream-ai-job-results).
example: |-
### Top 5 Products by Revenue
1. **Sunglasses** - $678,994
2. **Jeans** - $475,072
error:
type: object
description: >
**Only present in `FAILED` state.** Error details
explaining why the job failed.
properties:
code:
type: string
description: Machine-readable error code.
example: QUERY_EXECUTION_ERROR
message:
type: string
description: Human-readable error message.
example: Column 'revenue' not found in table 'orders'
detail:
type: string
description: Additional error detail or context.
example: The query timed out after 300 seconds
required:
- message
createdAt:
type: string
format: date-time
description: When the job was submitted.
example: '2025-01-15T10:00:00.000Z'
executionStartedAt:
type: string
format: date-time
description: >-
When execution began. Present once the job transitions
from `QUEUED` to `EXECUTING`. May be absent on jobs that
failed or were cancelled before execution started.
example: '2025-01-15T10:00:05.000Z'
completedAt:
type: string
format: date-time
description: >
**Present in `COMPLETE` and `FAILED` states.** When the
job finished (successfully or with error).
example: '2025-01-15T10:01:30.000Z'
cancelledAt:
type: string
format: date-time
description: |
When the job was cancelled.
example: '2025-01-15T10:00:12.000Z'
cancelledBy:
type: string
format: uuid
description: >
**Only present in `CANCELLED` state.** User ID of who
cancelled the job.
example: 990e8400-e29b-41d4-a716-446655440004
updatedAt:
type: string
format: date-time
description: When the job record was last modified.
example: '2025-01-15T10:00:05.000Z'
examples:
queued:
summary: QUEUED — job is waiting to be picked up
value:
id: 550e8400-e29b-41d4-a716-446655440000
state: QUEUED
prompt: What are the top 5 products by revenue?
conversationId: 660e8400-e29b-41d4-a716-446655440001
modelId: 770e8400-e29b-41d4-a716-446655440002
branchId: null
organizationId: 880e8400-e29b-41d4-a716-446655440003
userId: 990e8400-e29b-41d4-a716-446655440004
topicName: null
omniChatUrl: >-
https://my-org.omni.co/chat/660e8400-e29b-41d4-a716-446655440001
createdAt: '2025-01-15T10:00:00.000Z'
updatedAt: '2025-01-15T10:00:00.000Z'
executing:
summary: EXECUTING — AI is working through iterations
value:
id: 550e8400-e29b-41d4-a716-446655440000
state: EXECUTING
prompt: What are the top 5 products by revenue?
conversationId: 660e8400-e29b-41d4-a716-446655440001
modelId: 770e8400-e29b-41d4-a716-446655440002
branchId: null
organizationId: 880e8400-e29b-41d4-a716-446655440003
userId: 990e8400-e29b-41d4-a716-446655440004
topicName: order_items
omniChatUrl: >-
https://my-org.omni.co/chat/660e8400-e29b-41d4-a716-446655440001
progress:
iteration: 2
message: 'Running query: Top products by revenue'
updatedAt: '2025-01-15T10:00:08.000Z'
createdAt: '2025-01-15T10:00:00.000Z'
executionStartedAt: '2025-01-15T10:00:05.000Z'
updatedAt: '2025-01-15T10:00:08.000Z'
complete:
summary: COMPLETE — job finished successfully
value:
id: 550e8400-e29b-41d4-a716-446655440000
state: COMPLETE
prompt: What are the top 5 products by revenue?
conversationId: 660e8400-e29b-41d4-a716-446655440001
modelId: 770e8400-e29b-41d4-a716-446655440002
branchId: null
organizationId: 880e8400-e29b-41d4-a716-446655440003
userId: 990e8400-e29b-41d4-a716-446655440004
topicName: order_items
omniChatUrl: >-
https://my-org.omni.co/chat/660e8400-e29b-41d4-a716-446655440001
resultSummary: |-
### Top 5 Products by Revenue
1. **Sunglasses** - $678,994
2. **Jeans** - $475,072
createdAt: '2025-01-15T10:00:00.000Z'
executionStartedAt: '2025-01-15T10:00:05.000Z'
completedAt: '2025-01-15T10:01:30.000Z'
updatedAt: '2025-01-15T10:01:30.000Z'
failed:
summary: FAILED — job encountered an error
value:
id: 550e8400-e29b-41d4-a716-446655440000
state: FAILED
prompt: What are the top 5 products by revenue?
conversationId: 660e8400-e29b-41d4-a716-446655440001
modelId: 770e8400-e29b-41d4-a716-446655440002
branchId: null
organizationId: 880e8400-e29b-41d4-a716-446655440003
userId: 990e8400-e29b-41d4-a716-446655440004
topicName: order_items
omniChatUrl: >-
https://my-org.omni.co/chat/660e8400-e29b-41d4-a716-446655440001
error:
code: QUERY_EXECUTION_ERROR
message: Column 'revenue' not found in table 'orders'
detail: The query timed out after 300 seconds
createdAt: '2025-01-15T10:00:00.000Z'
executionStartedAt: '2025-01-15T10:00:05.000Z'
completedAt: '2025-01-15T10:01:30.000Z'
updatedAt: '2025-01-15T10:01:30.000Z'
cancelled:
summary: CANCELLED — job was cancelled by a user
value:
id: 550e8400-e29b-41d4-a716-446655440000
state: CANCELLED
prompt: What are the top 5 products by revenue?
conversationId: 660e8400-e29b-41d4-a716-446655440001
modelId: 770e8400-e29b-41d4-a716-446655440002
branchId: null
organizationId: 880e8400-e29b-41d4-a716-446655440003
userId: 990e8400-e29b-41d4-a716-446655440004
topicName: null
omniChatUrl: >-
https://my-org.omni.co/chat/660e8400-e29b-41d4-a716-446655440001
createdAt: '2025-01-15T10:00:00.000Z'
executionStartedAt: '2025-01-15T10:00:05.000Z'
cancelledAt: '2025-01-15T10:00:12.000Z'
cancelledBy: 990e8400-e29b-41d4-a716-446655440004
updatedAt: '2025-01-15T10:00:12.000Z'
'400':
description: |
Bad Request
Possible error messages:
- `Invalid job ID format. Must be a valid UUID.`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: |
Unauthorized
Possible error messages:
- `Missing or invalid API key`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Job not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: '404'
detail: Job not found
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
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'
InternalServerError:
description: Internal Server Error
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`
````