> ## 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.
# List AI Routines
>
AI routines must be enabled for your organization to use this endpoint.
List AI Routines for the calling user, newest first. Includes routines paused by the owner or disabled by Omni, but excludes deleted routines.
Use `pageInfo.nextCursor` from one response as the `cursor` query parameter on the next request.
## OpenAPI
````yaml /api/openapi.yaml get /v1/ai/routines
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:
get:
tags:
- AI Routines
summary: List AI Routines
description: >
AI routines must be enabled for your organization to use this endpoint.
List AI Routines for the calling user, newest first. Includes routines
paused by the owner or disabled by Omni, but excludes deleted routines.
Use `pageInfo.nextCursor` from one response as the `cursor` query
parameter on the next request.
operationId: aiRoutinesList
parameters:
- name: cursor
in: query
schema:
type: string
example: eyJpZCI6IjEyMzQ1In0
required: false
description: Cursor for pagination from previous response `nextCursor`
- name: pageSize
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
example: 20
required: false
description: Number of results per page (1-100, integer)
- name: sortDirection
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
example: desc
required: false
description: Sort direction for results
- name: sortField
in: query
schema:
type: string
required: false
description: Field to sort results by
- name: userId
in: query
schema:
type: string
format: uuid
required: false
description: |
**Requires an Organization API key**. Target user membership ID.
responses:
'200':
description: List of AI Routines
content:
application/json:
schema:
type: object
required:
- pageInfo
- records
properties:
pageInfo:
$ref: '#/components/schemas/PageInfo'
records:
type: array
items:
$ref: '#/components/schemas/Routine'
description: Routines returned for this request, newest first.
'400':
description: Invalid pagination cursor or `userId` value.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError400'
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: >
Forbidden
Possible error messages:
- `User does not have USE_AI permission`
- `AI Routines feature is not enabled (aiScheduledTasks flag
required)`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: |
Not found.
Possible causes:
- The `userId` membership was not found in the organization.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError404'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
PageInfo:
type: object
description: Pagination information for paginated responses.
properties:
hasNextPage:
type: boolean
description: Indicates if there are more records available.
nextCursor:
type: string
nullable: true
description: Cursor for the next page of results. `null` if no more results.
pageSize:
type: integer
description: Number of records per page.
totalRecords:
type: integer
description: Total number of records matching the query.
Routine:
type: object
properties:
branchId:
type: string
nullable: true
format: uuid
description: Branch of the shared model the prompt runs against, or null.
createdAt:
type: string
description: ISO 8601 timestamp when the routine was created.
description:
type: string
nullable: true
description: Display-only notes about the routine, or null.
destination:
$ref: '#/components/schemas/RoutineDestination'
disabled:
type: boolean
description: Whether the owner has paused the routine.
id:
type: string
format: uuid
description: The unique identifier of the routine.
lastRun:
$ref: '#/components/schemas/RoutineLastRun'
modelId:
type: string
format: uuid
description: The shared model the prompt runs against.
name:
type: string
description: Customer-visible name of the routine, used as the email subject.
prompt:
type: string
description: Natural language prompt Omni runs on each scheduled run.
recipientCount:
type: integer
description: >-
Number of distinct deliverable recipients after expanding user
groups and removing duplicates.
schedule:
type: string
description: >-
Six-field cron expression (minute, hour, day-of-month, month,
day-of-week, year; use `?` for an unspecified day field).
systemDisabled:
type: boolean
description: >-
Whether Omni disabled the routine because it could no longer run
successfully or safely.
systemDisabledReason:
type: string
nullable: true
description: Reason Omni disabled the routine, or null.
timezone:
type: string
description: IANA timezone identifier used to evaluate the schedule.
topicName:
type: string
nullable: true
description: Topic scoping query generation, or null.
updatedAt:
type: string
description: ISO 8601 timestamp when the routine was last updated.
required:
- branchId
- createdAt
- description
- destination
- disabled
- id
- lastRun
- modelId
- name
- prompt
- recipientCount
- schedule
- systemDisabled
- systemDisabledReason
- timezone
- topicName
- updatedAt
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
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example:
message:
type: string
description: Detailed error description
example:
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
RoutineDestination:
oneOf:
- $ref: '#/components/schemas/RoutineEmailDestination'
- $ref: '#/components/schemas/RoutineSlackDestination'
discriminator:
propertyName: type
mapping:
email:
$ref: '#/components/schemas/RoutineEmailDestination'
slack:
$ref: '#/components/schemas/RoutineSlackDestination'
description: >-
Single delivery destination for the routine — email or Slack. To send
results to multiple destinations, create one routine per destination.
RoutineLastRun:
type: object
nullable: true
required:
- completedAt
- label
- state
description: >-
Most recent completed run, or null if the routine has never completed a
run.
properties:
completedAt:
type: string
nullable: true
description: ISO 8601 timestamp the last completed run finished.
label:
type: string
description: User-visible status of the last completed run.
example: Delivered
state:
type: string
description: Machine-readable status of the last completed run.
example: COMPLETE
RoutineEmailDestination:
type: object
required:
- type
additionalProperties: false
description: Email delivery configuration for the routine.
properties:
recipientEmails:
type: array
items:
type: string
format: email
maxItems: 100
default: []
description: Email addresses that receive each scheduled run of the routine.
example:
- blob.ross@blobsrus.com
- blob.the.builder@blobsrus.com
type:
type: string
enum:
- email
description: >-
Selects email delivery — each scheduled run is sent to the listed
email recipients and user groups.
example: email
userGroupIds:
type: array
items:
type: string
format: uuid
maxItems: 100
default: []
description: >-
User group IDs whose active members receive each scheduled run. Omni
expands each group to the members' current email addresses when the
routine runs.
example:
- 550e8400-e29b-41d4-a716-446655440000
RoutineSlackDestination:
type: object
required:
- recipientId
- slackRecipientType
- type
additionalProperties: false
description: >-
Slack delivery configuration for the routine. Requires a Slack workspace
connected to Omni; to deliver to a private channel, invite the Omni
Slackbot to it first.
properties:
recipientId:
type: string
minLength: 1
description: >-
The Slack channel ID (e.g. `C01234567`) or user ID (e.g.
`U01234567`) that receives each scheduled run. Exactly one recipient
per Slack routine.
example: C01234567
slackRecipientType:
type: string
enum:
- channel
- users
description: >-
Whether `recipientId` is a Slack channel or a user (delivered as a
direct message).
example: channel
type:
type: string
enum:
- slack
description: >-
Selects Slack delivery — each scheduled run is posted to one Slack
channel or sent as a direct message to one user.
example: slack
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#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`
````