Create AI job
Submit a new AI job for asynchronous execution. The AI will analyze the prompt, generate and execute queries against the specified model, and produce a summarized answer.
Jobs are processed by a background worker and typically complete within 15–60 seconds. Use Get AI job status to poll for status, or configure a webhookUrl to receive a notification when the job completes. Optionally continue an existing conversation by providing a conversationId.
Webhook notifications
If awebhookUrl is configured, it will receive a POST with the following body when the job reaches a terminal state:
X-Omni-Signature-Timestamp-unixX-Omni-Signature- (sha256=HMAC(timestamp.body, secret))
result_summary which can contain actual data values from query results. Full result detail (CSV data, query definitions, actions) requires calling the Stream AI job results endpoint with credentials.Authorizations
Can be either an Organization API Key or Personal Access Token (PAT).
Include in the Authorization header as: Bearer YOUR_TOKEN
Query Parameters
Requires an Organization API key. The ID of the user to run the query as.
Personal Access Tokens (PATs) cannot use this parameter to act on behalf of other users.
Body
The ID of the model to run the AI job against
Natural language instruction describing the desired task
Optional conversation ID to continue an existing conversation
Optional branch ID for the model. Must be a branch of the shared model specified by modelId.
Queries run against the branch model, and if the Omni Agent makes model changes, they are written to this branch instead of a newly created one. If omitted and the Agent makes model changes, a new branch is created automatically.
Topic name to scope query generation.
If not provided, the AI will automatically select the best topic based on the prompt. For multi-turn conversations, the AI will carry forward the topic from the previous turn.
The topic must exist in the model and be allowed by any ai_chat_topics restrictions or the API will return a 404. Use the Pick topic endpoint to programmatically determine the right topic.
When true, real-time progress events are sent using POST to the defined webhookUrl during execution (e.g., "Searching for revenue fields", "Query returned 42 rows"). webhookUrl is required if enabled.
Progress events are best-effort: single attempt, no retries, failures do not affect job execution.
An optional webhook URL to receive webhook updates. Always receives a terminal event (job.complete or job.failed) when the job finishes.
When progressWebhookEnabled: true, also receives real-time progress events during execution. Required if progressWebhookEnabled: true.
An HMAC-SHA256 secret for signing webhook payloads
Opaque metadata passed back unchanged in webhook payloads
Optional image or PDF attachments giving the AI additional visual context alongside the prompt (e.g., a screenshot or export of a legacy Tableau/Power BI/Looker dashboard being migrated).
Image files are limited to 3MB each; text files such as CSVs have a ~50KB limit. All attachments in a single request share a combined size budget of roughly 15 MB, shared with your prompt text. Requests can be rejected if the attachments exceed this limit, whether on their own or combined with the prompt. In this case, try attaching fewer files or using smaller/lower-resolution exports.
Attachments are stored internally and never exposed over the public API. They will not appear in job status responses, results, or webhook payloads.5Response
AI job created successfully