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

# List schedule runs

> List Schedule Run execution records.

`GET /api/v1/forward/schedule_runs`

Lists Schedule Runs for an Identity. Pass `schedule_id` to narrow results to one Schedule.

## Headers

| Header          | Required | Description    |
| --------------- | -------- | -------------- |
| `Authorization` | Yes      | `Bearer <PAT>` |

## Query parameters

| Parameter      | Type    | Required | Default                                 | Description                                                          |
| -------------- | ------- | -------- | --------------------------------------- | -------------------------------------------------------------------- |
| `identity_id`  | string  | Yes      | Forward Identity ID that owns the runs. |                                                                      |
| `schedule_id`  | string  | No       | -                                       | Filter by Schedule ID.                                               |
| `status`       | string  | No       | -                                       | Filter by `pending`, `running`, `completed`, `failed`, or `skipped`. |
| `trigger_type` | string  | No       | -                                       | Filter by `schedule` or `manual`.                                    |
| `has_error`    | boolean | No       | -                                       | Filter to runs with or without an error.                             |
| `limit`        | integer | No       | 20                                      | Items per page. Maximum 100.                                         |
| `after_id`     | string  | No       | -                                       | Cursor for records after the given Run ID.                           |
| `before_id`    | string  | No       | -                                       | Cursor for records before the given Run ID.                          |

## Example request

```bash theme={null}
curl -s -X GET 'https://api.qoder.com/api/v1/forward/schedule_runs?identity_id=idn_019eabc123&schedule_id=sched_019f00112233445566778899aabbccdd&limit=20' \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "srun_019f00112233445566778899aabbccdd",
      "schedule_id": "sched_019f00112233445566778899aabbccdd",
      "identity_id": "idn_019eabc123",
      "template_id": "tmpl_support",
      "session_id": "sess_019ec55a68b37e1e8d660691af161ab4",
      "status": "completed",
      "trigger_context": {
        "type": "schedule",
        "scheduled_at": "2026-06-22T01:00:00Z"
      },
      "error": null,
      "result_payload": "Today's technology highlights: ...",
      "push_sink": "im_channel",
      "push_status": "succeeded",
      "push_finished_at": "2026-06-22T01:00:21Z",
      "attempt": 1,
      "triggered_at": "2026-06-22T01:00:00Z",
      "started_at": "2026-06-22T01:00:03Z",
      "completed_at": "2026-06-22T01:00:20Z",
      "duration_ms": 17000,
      "created_at": "2026-06-22T01:00:00Z"
    }
  ],
  "first_id": "srun_019f00112233445566778899aabbccdd",
  "last_id": "srun_019f00112233445566778899aabbccdd",
  "has_more": false
}
```

## Response fields

| Field      | Type         | Description                               |
| ---------- | ------------ | ----------------------------------------- |
| `data`     | array        | Schedule Run objects on the current page. |
| `first_id` | string\|null | ID of the first run on this page.         |
| `last_id`  | string\|null | ID of the last run on this page.          |
| `has_more` | boolean      | Whether more records remain.              |

Each `data[]` item is a Schedule Run object with the same fields documented by Get Schedule Run, including `trigger_context`, `error`, `push_sink`, `push_status`, and execution timestamps.

## Errors

| HTTP | Type                    | Code                      | Trigger                              |
| ---- | ----------------------- | ------------------------- | ------------------------------------ |
| 400  | `invalid_request_error` | `invalid_identity`        | `identity_id` is missing or invalid. |
| 400  | `invalid_request_error` | `invalid_pagination`      | Pagination parameters are invalid.   |
| 401  | `authentication_error`  | `authentication_required` | PAT invalid or expired.              |

## Notes

* Schedule Runs are independent resources.
* `completed`, `failed`, and `skipped` are terminal statuses.
* `push_status` describes IM streaming delivery and is independent from the main run `status`.

## Related

<CardGroup cols={2}>
  <Card title="Run a schedule" icon="play" href="/cloud-agents/api/forward/schedules/run" />

  <Card title="Get schedule run" icon="file-lines" href="/cloud-agents/api/forward/schedule-runs/get" />
</CardGroup>