> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# List schedules
> Lists all schedules attached to the specified agent, most recent first.
Lists every schedule attached to the specified agent, most recent first. Returns an envelope with a `schedules` array — empty if the agent has none.
See [Agent Schedules](/docs/agents/agent-schedules) for the full schedule document shape.
```bash List theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.orq.ai/v3/agents/customer_digest/schedules \
-H "Authorization: Bearer $ORQ_API_KEY"
```
```json 200 OK theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"schedules": [
{
"_id": "01KPN29WWKSK0VDPJNTKZPVNRB",
"workspace_id": "cd185327-a8a5-4e55-ac9e-51c8e8b7f0e5",
"agent_key": "customer_digest",
"type": "cron",
"expression": "0 0 9 * * mon-fri",
"is_active": true,
"generation": 2,
"payload": {
"input": "Generate the morning briefing for {{region}}",
"variables": { "region": "EMEA" }
},
"created_by_id": "apk_01KPM5XHYF7NXZ1S3XK2J8Q4B7",
"created": "2026-04-15T12:00:00Z",
"updated": "2026-04-20T09:30:00Z",
"last_triggered_at": "2026-04-20T09:00:02Z",
"trigger_count": 12
},
{
"_id": "01KPMQ9S5ZQ3K8B2XJV0N7R1GZ",
"workspace_id": "cd185327-a8a5-4e55-ac9e-51c8e8b7f0e5",
"agent_key": "customer_digest",
"type": "once",
"expression": "@at 2026-05-01T09:00:00Z",
"is_active": true,
"generation": 1,
"payload": {
"input": "Follow-up on last month's outage report"
},
"created_by_id": "apk_01KPM5XHYF7NXZ1S3XK2J8Q4B7",
"created": "2026-04-19T16:00:00Z",
"updated": "2026-04-19T16:00:00Z",
"trigger_count": 0
}
]
}
```
```json 200 OK (no schedules) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"schedules": []
}
```
## OpenAPI
````yaml get /v3/agents/{agent_key}/schedules
openapi: 3.1.0
info:
title: orq.ai API
version: '2.0'
description: orq.ai API documentation
servers:
- url: https://api.orq.ai
security:
- ApiKey: []
tags:
- name: Guardrail Rules
- name: Policies
- name: Routing Rules
- name: Files
description: File upload and retrieval operations.
- name: FilesService
- name: Projects
description: Projects organize resources within a workspace
- name: ProjectsService
- name: Skills
description: >-
Skills are modular instructions you can use to codify processes and
conventions
- name: SkillsService
- name: Responses
- description: >-
Run agents on a cadence — cron, interval, or one-off. Minimum firing
interval is 1 hour.
name: Agent Schedules
- name: Reporting
description: >-
GenAI reporting API over canonical analytics rollups. Accepts a metric
name, time range, grain, group-by, and filters; returns a typed time
series and optional totals.
- name: ReportingService
description: |-
ReportingService exposes a single QueryReport RPC that maps allowlisted
analytics payloads onto safe rollup queries. Callers never send SQL;
the backend picks the rollup family and grain from the metric
catalogue, the requested range, and the requested grouping.
externalDocs:
url: https://docs.orq.ai
description: orq.ai Documentation
paths:
/v3/agents/{agent_key}/schedules:
get:
tags:
- Agent Schedules
summary: List schedules
description: Lists all schedules attached to the specified agent, most recent first.
operationId: list-agent-schedules
parameters:
- description: The unique routing key of the agent the schedule belongs to.
in: path
name: agent_key
required: true
schema:
description: The unique routing key of the agent the schedule belongs to.
type: string
responses:
'200':
content:
application/json:
schema:
additionalProperties: false
properties:
schedules:
items:
$ref: '#/components/schemas/PublicSchedule'
type:
- array
- 'null'
required:
- schedules
type: object
description: Schedules listed (empty array if none).
components:
schemas:
PublicSchedule:
additionalProperties: false
properties:
_id:
description: ULID identifying this schedule.
type: string
agent_key:
type: string
agent_tag:
description: >-
Pinned agent version. Omit to always run the agent's current active
version.
type: string
created:
format: date-time
type: string
created_by_id:
description: ID of the API key that created the schedule.
type: string
expression:
description: >-
Cron expression (6-field, seconds required), @every duration, @at
RFC3339 timestamp, or a predefined descriptor like @hourly/@daily.
type: string
generation:
description: >-
Monotonic counter bumped when the schedule's firing cadence changes.
Used by the consumer to skip stale in-flight triggers.
format: int64
type: integer
is_active:
description: >-
Whether the schedule is currently firing. once schedules flip to
false automatically after firing.
type: boolean
last_triggered_at:
description: Timestamp of the most recent firing, if any.
format: date-time
type: string
payload:
$ref: '#/components/schemas/PublicSchedulePayload'
trigger_count:
description: Total firings since creation or last expression/type change.
format: int64
type: integer
type:
description: Schedule type.
enum:
- cron
- once
- interval
type: string
updated:
format: date-time
type: string
required:
- _id
- agent_key
- type
- expression
- is_active
- generation
- payload
- created_by_id
- created
- updated
- trigger_count
type: object
PublicSchedulePayload:
additionalProperties: false
properties:
input:
description: >-
Input to pass to the agent on each firing. Same shape as the
Responses API input — a string or an array of input items.
memory_entity_id:
description: Optional memory store entity ID to attach to each run.
type: string
metadata:
additionalProperties: {}
description: >-
Opaque key/value pairs attached to every response generated by this
schedule.
type: object
variables:
additionalProperties: {}
description: >-
Template variables substituted into instructions. Supports secret
values: {"secret": true, "value": "..."}.
type: object
type: object
securitySchemes:
ApiKey:
type: http
scheme: bearer
bearerFormat: JWT
````