> ## 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.



## 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:
  - description: List models available through the AI Router.
    name: Models
  - name: Guardrail Rules
  - name: Policies
  - name: Routing Rules
  - name: API keys
    description: >-
      API keys authenticate programmatic access to the workspace. The unified
      key model exposes opaque tokens, per-domain access grants, and budget /
      rate-limit constraints (see ADR 0001 and ADR 0002).
  - name: Budgets
    description: >-
      Budgets govern spend, token usage, and request rate across six scopes:
      workspace, project, identity, api-key, provider, and model. A budget is
      hierarchical and defense-in-depth — every applicable budget is a hard
      gate, and the most restrictive one wins per dimension (see ADR 0007).
  - name: Documentation
    description: >-
      Search the orq.ai documentation. Proxies the workspace's query to the
      hosted docs search index.
  - name: Files
    description: File upload and retrieval operations.
  - name: Identities
    description: >-
      Identities represent end users from your system for usage and engagement
      tracking.
  - name: Projects
    description: Projects organize resources within a workspace
  - name: Skills
    description: >-
      Skills are modular instructions you can use to codify processes and
      conventions
  - name: Responses
  - description: >-
      Run agents on a cadence — cron, interval, or one-off. Minimum firing
      interval is 1 hour.
    name: Agent Schedules
  - name: Embeddings
  - 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.
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

````