---
title: "Retrieve a schedule"
method: GET
path: "/api/v1/agents/{agent}/schedules/{schedule}"
---

# Retrieve a schedule

`GET /api/v1/agents/{agent}/schedules/{schedule}`

Returns a single schedule belonging to the specified agent. Use this endpoint
to fetch the current state, next run time, and configuration of an individual
schedule.

Requires an app-scoped API key. Both the agent and the schedule must belong
to the app identified by the key. Returns 404 if the schedule does not exist
or belongs to a different agent.

## Path parameters

- `agent` string, required
- `schedule` string, required

## Response `200`

Successful response

- AgentSchedule — A scheduled task created by an agent. Supports one-time and recurring (cron-based) execution patterns.
  - `agent` string — ID of the agent that owns this schedule (`agi_...`).
  - `app` string — ID of the application the schedule belongs to (`dap_...`).
  - `created_at` string, date-time — When the schedule was created (ISO 8601).
  - `cron_expression` string — Standard cron expression defining the recurrence pattern (e.g. `"0 9 * * 1"`). Present only when `schedule_type` is `"recurring"`. `null` for one-time schedules.
  - `id` string, required — Schedule ID (`asc_...`).
  - `instructions` string — The task description the agent will execute when this schedule fires.
  - `last_run_at` string, date-time — UTC datetime of the most recent successful execution. `null` if the schedule has never run.
  - `max_runs` integer — Maximum number of times a recurring schedule may fire before automatically transitioning to `"completed"`. `null` means no limit.
  - `metadata` object — Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform.
  - `next_run_at` string, date-time — UTC datetime of the next planned execution. `null` if the schedule has completed, been cancelled, or has not yet been computed.
  - `run_count` integer — Total number of times this schedule has fired.
  - `schedule_type` string — Determines how the schedule repeats. `"once"` fires a single time at `scheduled_at` then transitions to `"completed"`. `"recurring"` fires on the `cron_expression` and reschedules automatically.
  - `scheduled_at` string, date-time — The exact UTC datetime at which a one-time schedule fires. Present only when `schedule_type` is `"once"`. `null` for recurring schedules.
  - `status` string — Current lifecycle status of the schedule. One of `"active"` (will fire as planned), `"paused"` (temporarily suspended), `"completed"` (has run its last execution), `"cancelled"` (manually stopped), or `"expired"` (past its valid window).
  - `thread` string — Thread ID (`thr_...`) this schedule is bound to. When set, the scheduled task is delivered into the thread rather than creating a new session. `null` for session-based schedules.
  - `timezone` string — IANA timezone name used to interpret the cron expression or `scheduled_at` (e.g. `"America/New_York"`). Defaults to `"Etc/UTC"`.
  - `updated_at` string, date-time — When the schedule was last modified (ISO 8601).

## Other responses

- `401` — Unauthorized
- `403` — Forbidden - app scope required
- `404` — Schedule not found

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/versions/a8772b442f86/schema)