> ## 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.
# Retrieve schedule
> Retrieves a single schedule by ID.
Returns the full schedule document, including `trigger_count`, `last_triggered_at`, and the current `generation` counter. Useful for checking state after creation or verifying a schedule fired as expected.
See [Agent Schedules](/docs/agents/agent-schedules) for field semantics.
```bash Retrieve theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.orq.ai/v3/agents/customer_digest/schedules/01KPN29WWKSK0VDPJNTKZPVNRB \
-H "Authorization: Bearer $ORQ_API_KEY"
```
```json 200 OK theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"_id": "01KPN29WWKSK0VDPJNTKZPVNRB",
"workspace_id": "cd185327-a8a5-4e55-ac9e-51c8e8b7f0e5",
"agent_key": "customer_digest",
"agent_tag": "v2",
"type": "cron",
"expression": "0 0 9 * * mon-fri",
"is_active": true,
"generation": 2,
"payload": {
"input": "Generate the morning briefing for {{region}}",
"variables": { "region": "EMEA" },
"metadata": { "run_source": "daily-briefing" }
},
"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
}
```
```json 404 Not Found theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"error": {
"code": "schedule_not_found",
"message": "Schedule not found"
}
}
```
## OpenAPI
````yaml get /v3/agents/{agent_key}/schedules/{schedule_id}
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/{schedule_id}:
get:
tags:
- Agent Schedules
summary: Retrieve schedule
description: Retrieves a single schedule by ID.
operationId: retrieve-agent-schedule
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
- description: The schedule's ULID, as returned from create.
in: path
name: schedule_id
required: true
schema:
description: The schedule's ULID, as returned from create.
type: string
responses:
'200':
content:
application/json:
schema:
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
description: Schedule retrieved.
'404':
content:
application/json:
schema:
additionalProperties: false
properties:
error:
$ref: '#/components/schemas/PublicScheduleErrorDetail'
required:
- error
type: object
description: Schedule not found, or belongs to a different agent.
components:
schemas:
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
PublicScheduleErrorDetail:
additionalProperties: false
properties:
code:
description: >-
Stable error code, e.g. invalid_expression, schedule_not_found,
agent_not_found.
type: string
message:
description: Human-readable error description.
type: string
required:
- code
- message
type: object
securitySchemes:
ApiKey:
type: http
scheme: bearer
bearerFormat: JWT
````