> ## 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.
# Run AI routine now
>
AI routines must be enabled for your organization to use this endpoint.
Run an existing routine immediately, in addition to its schedule — e.g. to get an off-cycle result or verify a routine produces the email you expect.
Executes once using the routine owner's permissions and delivers the AI response to every recipient configured on the routine. Returns as soon as the run has started; the result arrives asynchronously via the routine's normal email delivery.
If a run is already in progress, the endpoint returns `409` rather than starting a second one. Manual runs that hit broken configuration will return `400` but not pause the schedule.
## OpenAPI
````yaml /api/openapi.yaml post /v1/ai/routines/{routineId}/trigger
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 Eval
description: >-
AI evaluation: 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 AI Routines: schedule recurring AI-powered tasks to run
automatically on your data.
- name: Documents v2
description: >
A draft-based workflow for creating and editing documents: create a
document, patch a draft, then publish. Replaces the one-shot `PUT`/`PATCH`
v1 document write endpoints.
- name: Documents
description: Create, retrieve, and manage documents
- 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: 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/routines/{routineId}/trigger:
post:
tags:
- AI Routines
summary: Run AI routine now
description: >
AI routines must be enabled for your organization to use this endpoint.
Run an existing routine immediately, in addition to its schedule — e.g.
to get an off-cycle result or verify a routine produces the email you
expect.
Executes once using the routine owner's permissions and delivers the AI
response to every recipient configured on the routine. Returns as soon
as the run has started; the result arrives asynchronously via the
routine's normal email delivery.
If a run is already in progress, the endpoint returns `409` rather than
starting a second one. Manual runs that hit broken configuration will
return `400` but not pause the schedule.
operationId: triggerAIRoutine
parameters:
- name: id
in: path
schema:
type: string
format: uuid
required: true
description: The UUID of the routine.
- name: userId
in: query
required: false
schema:
type: string
format: uuid
description: |
**Requires an Organization API key**. Target user membership ID.
responses:
'202':
description: The run has started.
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: string
format: uuid
description: The ID of the run (scheduled job) that was started.
example: 990e8400-e29b-41d4-a716-446655440004
'400':
description: >
Bad request. Possible causes:
- Invalid routine ID
- Routine cannot run as configured (e.g. its model, branch, or owner
is no longer accessible)
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError400'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError401'
'403':
description: >-
AI routines or AI query generation are not enabled for the
organization, or a user-scoped API key tried to run another user's
routine.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError403'
'404':
description: >-
The routine does not exist or cannot be triggered (deleted, paused,
or disabled by Omni).
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError404'
'409':
description: A run is already in progress for this routine.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError409'
security:
- bearerAuth: []
components:
schemas:
ApiError400:
type: object
properties:
detail:
type: string
description: Human-readable error message describing what went wrong.
example: 'Bad Request: prompt: Required'
status:
type: integer
description: HTTP status code of the error.
example: 400
required:
- detail
- status
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
ApiError403:
type: object
properties:
detail:
type: string
description: Human-readable error message describing what went wrong.
example: 'Forbidden: AI query generation is not enabled for this organization'
status:
type: integer
description: HTTP status code of the error.
example: 403
required:
- detail
- status
ApiError404:
type: object
properties:
detail:
type: string
description: Human-readable error message describing what went wrong.
example: Model 770e8400-e29b-41d4-a716-446655440002 not found
status:
type: integer
description: HTTP status code of the error.
example: 404
required:
- detail
- status
ApiError409:
type: object
properties:
detail:
type: string
description: Human-readable error message describing what went wrong.
example: An active job already exists for this conversation
status:
type: integer
description: HTTP status code of the error.
example: 409
required:
- detail
- status
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`
````