> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List schedule runs

> Browse a schedule's fire history.

Returns the schedule's recent fires, newest first. Every fire produces a run record, including skipped and failed ones, so the history is gap-free. Runs are retained for 90 days.

**Returns** a paginated list of run records.

***

## Path parameters

<ParamField path="schedule_id" type="string" required>
  The schedule's id (UUID).
</ParamField>

## Query parameters

<ParamField query="page" type="integer" default="1">
  Page number (1-based).
</ParamField>

<ParamField query="size" type="integer" default="10">
  Items per page. Maximum: `1000`.
</ParamField>

<ParamField query="sort" type="string" default="-scheduled_for">
  Sort order. Options: `scheduled_for`, `-scheduled_for`.
</ParamField>

***

## The run record

<ResponseField name="id" type="string">
  Unique id for this run (UUID).
</ResponseField>

<ResponseField name="schedule_id" type="string">
  The schedule that fired.
</ResponseField>

<ResponseField name="status" type="string">
  Outcome of the fire: `created`, `skipped_overlap` (previous session still active), `skipped_quota` (organization at quota), or `error`.
</ResponseField>

<ResponseField name="scheduled_for" type="string">
  The fire's due time (UTC, RFC 3339).
</ResponseField>

<ResponseField name="session_id" type="string | null">
  The created session's id when `status` is `created`, otherwise `null`.
</ResponseField>

<ResponseField name="error" type="string | null">
  Failure detail when `status` is `error`.
</ResponseField>

<ResponseField name="triggered_manually" type="boolean">
  Whether the fire came from [Trigger](/computer-use-agents/schedules/trigger) rather than the cron cadence.
</ResponseField>

<ResponseField name="created_at" type="string">
  When the run record was written.
</ResponseField>

***

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://agp.eu.hcompany.ai/api/v2/schedules/9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f/runs" \
    -H "Authorization: Bearer $HAI_API_KEY"
  ```

  ```python Python theme={null}
  from hai_agents import Client

  client = Client()

  page = client.schedules.list_schedule_runs("9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f")
  for run in page.items:
      print(run.scheduled_for, run.status, run.session_id)
  ```

  ```typescript TypeScript theme={null}
  import { HaiAgentsClient } from "hai-agents";

  const client = new HaiAgentsClient();

  const page = await client.schedules.listScheduleRuns({ scheduleId: "9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f" });
  for (const run of page.items) {
    console.log(run.scheduledFor, run.status, run.sessionId);
  }
  ```
</CodeGroup>

```json Response theme={null}
{
  "items": [
    {
      "id": "3c2b1a09-8d7e-4f6a-b5c4-d3e2f1a0b9c8",
      "schedule_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f",
      "status": "created",
      "scheduled_for": "2026-07-03T07:00:00Z",
      "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "error": null,
      "triggered_manually": false,
      "created_at": "2026-07-03T07:00:02Z"
    },
    {
      "id": "2b1a0987-7c6d-4e5f-a4b3-c2d1e0f9a8b7",
      "schedule_id": "9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f",
      "status": "skipped_overlap",
      "scheduled_for": "2026-07-02T07:00:00Z",
      "session_id": null,
      "error": null,
      "triggered_manually": false,
      "created_at": "2026-07-02T07:00:01Z"
    }
  ],
  "page": 1,
  "total": 2
}
```

***

## Errors

| Status | Cause                                          |
| ------ | ---------------------------------------------- |
| `404`  | No schedule with this id in your organization. |