List schedule runs

List a schedule’s fires and the sessions they created.

GET /api/v2/schedules/{schedule_id}/runs

Python

from hai_agents import Client

client = Client()

page = client.schedules.list_schedule_runs(schedule_id)
for run in page.items:
    print(run.scheduled_for, run.status, run.session_id)

200

{
  "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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "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
}

Behavior

Runs come 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.

Path parameters

schedule_id · string · required

The schedule’s ID (UUID).

Query parameters

page · integer · default: "1"

Page number (1-based).

size · integer · default: "10"

Items per page. Maximum: 1000.

sort · string · default: "-scheduled_for"

Sort order. Options: scheduled_for, -scheduled_for.

Response

200 with a page envelope of run records.

Each run record, also returned by Trigger, has:

id · string

Unique ID for this run (UUID).

schedule_id · string

The schedule that fired.

status · string

Outcome of the fire: created, skipped_overlap (previous session still active), skipped_quota (organization at quota), or error.

scheduled_for · string

The fire’s due time (UTC, RFC 3339).

session_id · string | null

The created session’s ID when status is created, otherwise null.

error · string | null

Failure detail when status is error.

triggered_manually · boolean

Whether the fire came from Trigger rather than the cron cadence.

created_at · string

When the run record was written.

Python

from hai_agents import Client

client = Client()

page = client.schedules.list_schedule_runs(schedule_id)
for run in page.items:
    print(run.scheduled_for, run.status, run.session_id)

200

{
  "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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "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	Not found, or not in your organization.