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

# Trigger schedule execution

> Runs the schedule's payload immediately (≈10 seconds after the request, to stay above the NATS scheduler's minimum deliver-at margin). The schedule's regular cadence is unaffected. Inactive schedules return 400.

Runs the schedule's payload immediately (≈10 seconds after the request, the minimum dispatch margin). The schedule's regular cadence is unaffected — useful for smoke-testing a new schedule, UI "Run now" buttons, or manually re-running a missed execution.

Inactive schedules return `400 schedule_inactive`.

The run appears in traces as a `schedule.<agent_key>` leading span — same structure as an HTTP-invoked run. See [Agent Schedules](/docs/agents/agent-schedules#observability).

<RequestExample>
  ```bash Trigger theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.orq.ai/v3/agents/customer_digest/schedules/01KPN29WWKSK0VDPJNTKZPVNRB/execution \
    -H "Authorization: Bearer $ORQ_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 202 Accepted theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "status": "triggered",
    "schedule_id": "01KPN29WWKSK0VDPJNTKZPVNRB"
  }
  ```

  ```json 400 Schedule inactive theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "error": {
      "code": "schedule_inactive",
      "message": "Cannot trigger an inactive schedule"
    }
  }
  ```

  ```json 404 Not Found theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "error": {
      "code": "schedule_not_found",
      "message": "Schedule not found"
    }
  }
  ```
</ResponseExample>


## OpenAPI

````yaml post /v3/agents/{agent_key}/schedules/{schedule_id}/execution
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}/execution:
    post:
      tags:
        - Agent Schedules
      summary: Trigger schedule execution
      description: >-
        Runs the schedule's payload immediately (≈10 seconds after the request,
        to stay above the NATS scheduler's minimum deliver-at margin). The
        schedule's regular cadence is unaffected. Inactive schedules return 400.
      operationId: trigger-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:
        '202':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  schedule_id:
                    type: string
                  status:
                    description: Always "triggered" on success.
                    type: string
                required:
                  - status
                  - schedule_id
                type: object
          description: Execution scheduled for immediate delivery.
        '400':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  error:
                    $ref: '#/components/schemas/PublicScheduleErrorDetail'
                required:
                  - error
                type: object
          description: Schedule is inactive.
        '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:
    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

````