---
title: "Get AI job status"
method: GET
path: "/api/v1/ai/jobs/{jobId}"
tags: ["AI"]
---

# Get AI job status

`GET /api/v1/ai/jobs/{jobId}`

Get the current status 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).

## Path parameters

- `jobId` string, uuid, required — The unique identifier of the AI job

## Response `200`

Job status retrieved successfully. Check the state field to determine if the job is still running or has reached a terminal state.

- AiJobStatusResponse
  - `branchId` string, uuid, nullable, required — Branch ID used for model context, or null if querying the main shared model.
  - `cancelledAt` string, date-time — When the job was cancelled. Only present in CANCELLED state.
  - `cancelledBy` string, uuid — User ID of who cancelled the job. Only present in CANCELLED state.
  - `completedAt` string, date-time — When the job finished (successfully or with error). Present in COMPLETE and FAILED states.
  - `conversationId` string, uuid, required — The conversation this job belongs to. Use this to submit follow-up jobs in the same conversation thread.
  - `createdAt` string, date-time, required — When the job was submitted.
  - `error` object — Error details explaining why the job failed. Only present in FAILED state.
    - `code` string — Machine-readable error code.
    - `detail` string — Additional error detail or context.
    - `message` string, required — Human-readable error message.
  - `executionStartedAt` string, date-time — 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.
  - `id` string, uuid, required — The unique identifier for this job.
  - `modelId` string, uuid, nullable, required — The shared model ID used for query generation.
  - `omniChatUrl` string, uri, required — URL to view this conversation in the Omni chat interface. Opens the chat session where the job actions and results are visible.
  - `organizationId` string, uuid, required — The organization that owns this job.
  - `progress` object, nullable — Real-time progress information. Only present in EXECUTING state. Null if no progress has been reported yet. Updated in real-time as the AI works through iterations.
    - `iteration` integer, required — Current iteration number. The AI may take multiple iterations to refine queries and generate a complete answer.
    - `message` string, required — Human-readable status message describing what the AI is currently doing.
    - `updatedAt` string, date-time, required — When this progress update was recorded.
  - `prompt` string, required — The natural language prompt that was submitted.
  - `resultSummary` string — Markdown-formatted summary of the job result. Only present in COMPLETE state. For the full result with query details and data, use GET /api/v1/ai/jobs/{jobId}/result.
  - `state` 'CANCELLED' | 'COMPLETE' | 'DELIVERING' | 'EXECUTING' | 'FAILED' | 'QUEUED', required — Current state of the job. Terminal states are COMPLETE, FAILED, and CANCELLED. Poll until the job reaches a terminal state.
  - `topicName` string, nullable, required — Topic name used to scope query generation, or null if the AI selected the topic automatically.
  - `updatedAt` string, date-time, required — When the job record was last modified.
  - `userId` string, uuid, required — The user ID who created (or is associated with) this job.

## Other responses

- `400` — Invalid job ID format. Must be a valid UUID.
- `401` — Missing or invalid API key.
- `403` — Insufficient permissions. AI query generation must be enabled for the organization and the caller must have permission to use AI on the job's model.
- `404` — Job not found. The job may not exist or may belong to a different organization.

---

[API](https://skmtc.net/omniapp/apis/omni-api.md) · [All operations](https://skmtc.net/omniapp/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omniapp/omni-api/revisions/e77ab32034c9/schema)