---
title: API: runs
description: REST endpoints tagged runs — generated from the platform's OpenAPI contract (17 operations).
locale: en
version: 0.2.0
canonical: https://enterium-developer-docs.pages.dev/developers/api/runs/
---

> Documentation index: https://enterium-developer-docs.pages.dev/developers/llms.txt — every page of this portal has a Markdown twin at <route>.md; the frozen API contract is at https://enterium-developer-docs.pages.dev/developers/api/openapi.json.

:::note
Generated from the OpenAPI contract — do not edit by hand. Interactive explorer with full schemas: [https://entherium.duckdns.org:8443/reference](https://entherium.duckdns.org:8443/reference); frozen spec for this build: [openapi.json](/developers/api/openapi.json).
:::

## `GET /api/v1/runs`

List Runs

[Open as a page →](./get-runs/)

filtered, paginated run list (default sort createtime:desc).

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `status` | query | no | `string \| null` |  |
| `pipeline_id` | query | no | `string \| null` |  |
| `entity` | query | no | `string \| null` |  |
| `contract` | query | no | `integer \| null` |  |
| `limit` | query | no | `integer` |  |
| `offset` | query | no | `integer` |  |
| `sort` | query | no | `string` |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `RunListResponse` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `POST /api/v1/runs`

Launch Run

[Open as a page →](./post-runs/)

validate, create a queued run, stage the fixture, enqueue the job.

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | no | `string` | Optional. |

**Request body:** `application/json` — schema `RunLaunchRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `allow_regenerate` | `boolean` | no |  |
| `entity` | `string` | yes |  |
| `guid` | `integer` | yes |  |
| `mode` | `"live" \| "mock" \| "replay"` | no |  |
| `params` | `object` | no |  |
| `pipeline_id` | `string` | yes |  |
| `pipeline_variant` | `string \| null` | no |  |
| `pipeline_version` | `string \| null` | no |  |
| `steps` | `array of string \| null` | no |  |

_Example:_

```json
{
  "allow_regenerate": false,
  "entity": "generated_articles",
  "guid": 31567,
  "mode": "live",
  "params": {},
  "pipeline_id": "generate"
}
```

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `201` | Successful Response | `PipelineRunRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `409` | The record already generated successfully and allow_regenerate is false, or the entity is locked | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |
| `429` | Agent token: the concurrent-run cap for this token is reached | `ErrorResponse` |

_Example response (201):_

```json
{
  "createtime": "2026-09-03T02:14:04Z",
  "current_step": "make_article_structure",
  "entity_guid": 31567,
  "entity_name": "generated_articles",
  "guid": 1842,
  "metrics": {
    "llm_calls": 11
  },
  "mode": "live",
  "pipeline_id": "generate",
  "started_at": "2026-09-03T02:14:05Z",
  "started_by": "agent@entherium.dev",
  "status": "running",
  "steps_done": 7,
  "steps_total": 18,
  "trigger": "api",
  "updatetime": "2026-09-03T02:19:40Z"
}
```

## `GET /api/v1/runs/pipelines`

List Pipelines

[Open as a page →](./get-runs-pipelines/)

every registered pipeline definition.

**Auth:** `Authorization: Bearer <token>` required

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `array of PipelineDefRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |

## `GET /api/v1/runs/pipelines/{pipeline_id}`

Get Pipeline Def

[Open as a page →](./get-runs-pipelines-pipeline-id/)

a single pipeline definition.

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `pipeline_id` | path | yes | `string` |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `PipelineDefRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `GET /api/v1/runs/preflight`

Run Preflight

[Open as a page →](./get-runs-preflight/)

Can this run launch? Returns can_launch + blocking reasons WITHOUT creating a
run, so a caller can check quota, pool and pipeline state before spending a launch.

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `pipeline_id` | query | yes | `string` |  |
| `guid` | query | yes | `integer` |  |
| `entity` | query | no | `string \| null` |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `object` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `GET /api/v1/runs/schedules`

List Schedules

[Open as a page →](./get-runs-schedules/)

every schedule, newest first.

**Auth:** `Authorization: Bearer <token>` required

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `array of RunScheduleRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |

## `POST /api/v1/runs/schedules`

Create Schedule

[Open as a page →](./post-runs-schedules/)

create a schedule (validates pipeline + cron; computes next_fire_at).

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | no | `string` | Optional. |

**Request body:** `application/json` — schema `RunScheduleCreate`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cron` | `string` | yes |  |
| `enabled` | `boolean` | no |  |
| `entity` | `string` | yes |  |
| `max_targets_per_fire` | `integer` | no |  |
| `mode` | `string` | no |  |
| `name` | `string` | yes |  |
| `params` | `object` | no |  |
| `pipeline_id` | `string` | yes |  |
| `selector` | `object` | yes |  |
| `steps` | `array of string \| null` | no |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `201` | Successful Response | `RunScheduleRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `DELETE /api/v1/runs/schedules/{schedule_id}`

Delete Schedule

[Open as a page →](./delete-runs-schedules-schedule-id/)

delete a schedule (idempotent).

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `schedule_id` | path | yes | `integer` |  |
| `Idempotency-Key` | header | no | `string` | Optional. |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `204` | Successful Response | — |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `GET /api/v1/runs/schedules/{schedule_id}`

Get Schedule

[Open as a page →](./get-runs-schedules-schedule-id/)

a single schedule.

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `schedule_id` | path | yes | `integer` |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `RunScheduleRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `PATCH /api/v1/runs/schedules/{schedule_id}`

Update Schedule

[Open as a page →](./patch-runs-schedules-schedule-id/)

partial update; a changed cron recomputes next_fire_at.

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `schedule_id` | path | yes | `integer` |  |
| `Idempotency-Key` | header | no | `string` | Optional. |

**Request body:** `application/json` — schema `RunScheduleUpdate`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cron` | `string \| null` | no |  |
| `enabled` | `boolean \| null` | no |  |
| `max_targets_per_fire` | `integer \| null` | no |  |
| `mode` | `string \| null` | no |  |
| `name` | `string \| null` | no |  |
| `params` | `object \| null` | no |  |
| `selector` | `object \| null` | no |  |
| `steps` | `array of string \| null` | no |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `RunScheduleRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `POST /api/v1/runs/schedules/{schedule_id}/fire`

Fire Now

[Open as a page →](./post-runs-schedules-schedule-id-fire/)

fire now (same seam as the tick-loop / an external Cloud Scheduler).

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `schedule_id` | path | yes | `integer` |  |
| `Idempotency-Key` | header | no | `string` | Optional. |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `ScheduleFireResult` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `GET /api/v1/runs/schedules/{schedule_id}/runs`

Schedule Runs

[Open as a page →](./get-runs-schedules-schedule-id-runs/)

guids of the runs this schedule produced (params.schedule_id).

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `schedule_id` | path | yes | `integer` |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `array of integer` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `GET /api/v1/runs/{run_guid}`

Get Run

[Open as a page →](./get-runs-run-guid/)

run record + its steps + target card + pipeline def.

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `run_guid` | path | yes | `integer` |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `RunDetailResponse` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `POST /api/v1/runs/{run_guid}/cancel`

Cancel Run

[Open as a page →](./post-runs-run-guid-cancel/)

Cancel a run. A queued run is cancelled immediately; a run that is already
executing is marked cancelled but finishes its current execution (mid-flight
interruption is not implemented). Idempotent: a terminal run answers 409.

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `run_guid` | path | yes | `integer` |  |
| `Idempotency-Key` | header | no | `string` | Optional. |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `PipelineRunRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `409` | The run is already terminal | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

_Example response (200):_

```json
{
  "createtime": "2026-09-03T02:14:04Z",
  "current_step": "make_article_structure",
  "entity_guid": 31567,
  "entity_name": "generated_articles",
  "guid": 1842,
  "metrics": {
    "llm_calls": 11
  },
  "mode": "live",
  "pipeline_id": "generate",
  "started_at": "2026-09-03T02:14:05Z",
  "started_by": "agent@entherium.dev",
  "status": "running",
  "steps_done": 7,
  "steps_total": 18,
  "trigger": "api",
  "updatetime": "2026-09-03T02:19:40Z"
}
```

## `GET /api/v1/runs/{run_guid}/log`

Get Run Log

[Open as a page →](./get-runs-run-guid-log/)

assembled log; `step` filters to one step, `tail` keeps last N.

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `run_guid` | path | yes | `integer` |  |
| `step` | query | no | `string \| null` |  |
| `tail` | query | no | `integer \| null` |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `RunLogResponse` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `POST /api/v1/runs/{run_guid}/retry`

Retry Run

[Open as a page →](./post-runs-run-guid-retry/)

create a new run; `from_step` resumes from a step snapshot.

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `run_guid` | path | yes | `integer` |  |
| `Idempotency-Key` | header | no | `string` | Optional. |

**Request body:** `application/json` — schema `RunRetryRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from_step` | `string \| null` | no |  |

_Example:_

```json
{
  "from_step": "step_15_make_layout"
}
```

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `201` | Successful Response | `PipelineRunRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `409` | The run cannot be retried from its current state | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |
| `429` | Agent token: the concurrent-run cap for this token is reached | `ErrorResponse` |

_Example response (201):_

```json
{
  "createtime": "2026-09-03T02:14:04Z",
  "current_step": "make_article_structure",
  "entity_guid": 31567,
  "entity_name": "generated_articles",
  "guid": 1842,
  "metrics": {
    "llm_calls": 11
  },
  "mode": "live",
  "pipeline_id": "generate",
  "started_at": "2026-09-03T02:14:05Z",
  "started_by": "agent@entherium.dev",
  "status": "running",
  "steps_done": 7,
  "steps_total": 18,
  "trigger": "api",
  "updatetime": "2026-09-03T02:19:40Z"
}
```

## `GET /api/v1/runs/{run_guid}/steps`

Get Run Steps

[Open as a page →](./get-runs-run-guid-steps/)

the step rows of a run, ordered by seq/attempt.

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `run_guid` | path | yes | `integer` |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `array of RunStepRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |