---
title: "List schedules for an agent"
method: GET
path: "/api/v1/agents/{agent}/schedules"
---

# List schedules for an agent

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

Returns all schedules belonging to the specified agent in any status. Use the
`status` parameter to narrow results to a single lifecycle state.

Requires an app-scoped API key. The agent must belong to the app identified
by the key.

## Path parameters

- `agent` string, required

## Query parameters

- `status` string

## Response `200`

Successful response

- object — A list of schedule objects for the agent.
  - `data` object[] — Array of agent schedule objects matching the query.
    - `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

- `400` — Invalid status value
- `401` — Unauthorized
- `403` — Forbidden - app scope required

---

[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)