> ## 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.

# Get schedule run

> Retrieve one Schedule Run by ID.

`GET /api/v1/forward/schedule_runs/{run_id}`

Returns a single Schedule Run execution record. `identity_id` may be provided as an additional ownership constraint.

## Headers

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

## Path parameters

| Parameter | Type   | Required | Description      |
| --------- | ------ | -------- | ---------------- |
| `run_id`  | string | Yes      | Schedule Run ID. |

## Query parameters

| Parameter     | Type   | Required | Default | Description                               |
| ------------- | ------ | -------- | ------- | ----------------------------------------- |
| `identity_id` | string | No       | -       | Optional additional ownership constraint. |

## Example request

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

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "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,
  "error_message": 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"
}
```

## Response fields

| Field              | Type          | Description                                                               |
| ------------------ | ------------- | ------------------------------------------------------------------------- |
| `id`               | string        | Schedule Run ID.                                                          |
| `schedule_id`      | string        | Parent Schedule ID.                                                       |
| `identity_id`      | string        | Forward Identity ID.                                                      |
| `template_id`      | string        | Forward Template ID.                                                      |
| `session_id`       | string\|null  | Session created or reused for this run.                                   |
| `status`           | string        | `pending`, `running`, `completed`, `failed`, or `skipped`.                |
| `trigger_context`  | object        | Trigger source. `type` is `schedule` or `manual`.                         |
| `error`            | object\|null  | Structured error for failed or skipped runs.                              |
| `result_payload`   | string\|null  | Main text result.                                                         |
| `error_message`    | string\|null  | Human-readable error message. Structured details stay in `error`.         |
| `push_sink`        | string\|null  | Sink type used for IM delivery, or `null` when no delivery is configured. |
| `push_status`      | string        | `pending`, `succeeded`, `failed`, or `skipped`.                           |
| `push_finished_at` | string\|null  | IM delivery finish time.                                                  |
| `attempt`          | integer       | Attempt number. Currently `1`.                                            |
| `triggered_at`     | string        | Trigger time.                                                             |
| `started_at`       | string\|null  | Execution start time.                                                     |
| `completed_at`     | string\|null  | Execution end time.                                                       |
| `duration_ms`      | integer\|null | Execution duration in milliseconds.                                       |
| `created_at`       | string        | Record creation time.                                                     |

## Trigger context

| `type`     | Description                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `schedule` | Automatically triggered from the Schedule `trigger_policy`, such as `cron`, `once`, or `interval`. Automatic triggers include `scheduled_at`. |
| `manual`   | Manually triggered by `POST /api/v1/forward/schedules/{schedule_id}/run`.                                                                     |

## Run error

The `error` object describes structured failure or skip reasons. It may be returned when `status` is `failed` or `skipped`; it is `null` when `status` is `completed`.

| `error.type`                | Description                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| `concurrency_limit_reached` | The Schedule reached `execution.max_concurrent_runs`; this trigger was recorded but not executed. |
| `session_creation_failed`   | Forward failed to create or bind the execution Session.                                           |
| `execution_failed`          | Template execution failed.                                                                        |

## Errors

| HTTP | Type                   | Code                      | Trigger                                                                     |
| ---- | ---------------------- | ------------------------- | --------------------------------------------------------------------------- |
| 401  | `authentication_error` | `authentication_required` | PAT invalid or expired.                                                     |
| 404  | `not_found_error`      | `schedule_run_not_found`  | Run does not exist, is cross-tenant, or fails the `identity_id` constraint. |

## Notes

* `error.type=concurrency_limit_reached` means a run was recorded but skipped due to `max_concurrent_runs`.
* Poll this endpoint until `status` enters a terminal state.

## Related

<CardGroup cols={2}>
  <Card title="List schedule runs" icon="history" href="/cloud-agents/api/forward/schedule-runs/list" />

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