---
title: API: runs
description: REST-эндпоинты с тегом runs — сгенерировано из OpenAPI-контракта платформы (17 операций).
locale: ru
version: 0.2.0
canonical: https://enterium-developer-docs.pages.dev/developers/ru/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
Сгенерировано из OpenAPI-контракта — не редактировать руками. Сводки операций и описания полей приводятся на английском (дословно из контракта). Интерактивный обозреватель с полными схемами: [https://entherium.duckdns.org:8443/reference](https://entherium.duckdns.org:8443/reference); замороженная спецификация этой сборки: [openapi.json](/developers/api/openapi.json).
:::

## `GET /api/v1/runs`

List Runs

[Открыть отдельной страницей →](./get-runs/)

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

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `status` | query | нет | `string \| null` |  |
| `pipeline_id` | query | нет | `string \| null` |  |
| `entity` | query | нет | `string \| null` |  |
| `contract` | query | нет | `integer \| null` |  |
| `limit` | query | нет | `integer` |  |
| `offset` | query | нет | `integer` |  |
| `sort` | query | нет | `string` |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `RunListResponse` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `POST /api/v1/runs`

Launch Run

[Открыть отдельной страницей →](./post-runs/)

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

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | нет | `string` | Optional. |

**Тело запроса:** `application/json` — схема `RunLaunchRequest`

| Поле | Тип | Обязательно | Описание |
| --- | --- | --- | --- |
| `allow_regenerate` | `boolean` | нет |  |
| `entity` | `string` | да |  |
| `guid` | `integer` | да |  |
| `mode` | `"live" \| "mock" \| "replay"` | нет |  |
| `params` | `object` | нет |  |
| `pipeline_id` | `string` | да |  |
| `pipeline_variant` | `string \| null` | нет |  |
| `pipeline_version` | `string \| null` | нет |  |
| `steps` | `массив string \| null` | нет |  |

_Пример:_

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

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `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` |

_Пример ответа (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

[Открыть отдельной страницей →](./get-runs-pipelines/)

every registered pipeline definition.

**Авторизация:** нужен `Authorization: Bearer <token>`

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `массив PipelineDefRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |

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

Get Pipeline Def

[Открыть отдельной страницей →](./get-runs-pipelines-pipeline-id/)

a single pipeline definition.

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `pipeline_id` | path | да | `string` |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `PipelineDefRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Run Preflight

[Открыть отдельной страницей →](./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.

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `pipeline_id` | query | да | `string` |  |
| `guid` | query | да | `integer` |  |
| `entity` | query | нет | `string \| null` |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `object` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

List Schedules

[Открыть отдельной страницей →](./get-runs-schedules/)

every schedule, newest first.

**Авторизация:** нужен `Authorization: Bearer <token>`

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `массив RunScheduleRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |

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

Create Schedule

[Открыть отдельной страницей →](./post-runs-schedules/)

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

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | нет | `string` | Optional. |

**Тело запроса:** `application/json` — схема `RunScheduleCreate`

| Поле | Тип | Обязательно | Описание |
| --- | --- | --- | --- |
| `cron` | `string` | да |  |
| `enabled` | `boolean` | нет |  |
| `entity` | `string` | да |  |
| `max_targets_per_fire` | `integer` | нет |  |
| `mode` | `string` | нет |  |
| `name` | `string` | да |  |
| `params` | `object` | нет |  |
| `pipeline_id` | `string` | да |  |
| `selector` | `object` | да |  |
| `steps` | `массив string \| null` | нет |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `201` | Successful Response | `RunScheduleRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Delete Schedule

[Открыть отдельной страницей →](./delete-runs-schedules-schedule-id/)

delete a schedule (idempotent).

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `schedule_id` | path | да | `integer` |  |
| `Idempotency-Key` | header | нет | `string` | Optional. |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `204` | Successful Response | — |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Get Schedule

[Открыть отдельной страницей →](./get-runs-schedules-schedule-id/)

a single schedule.

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `schedule_id` | path | да | `integer` |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `RunScheduleRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Update Schedule

[Открыть отдельной страницей →](./patch-runs-schedules-schedule-id/)

partial update; a changed cron recomputes next_fire_at.

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `schedule_id` | path | да | `integer` |  |
| `Idempotency-Key` | header | нет | `string` | Optional. |

**Тело запроса:** `application/json` — схема `RunScheduleUpdate`

| Поле | Тип | Обязательно | Описание |
| --- | --- | --- | --- |
| `cron` | `string \| null` | нет |  |
| `enabled` | `boolean \| null` | нет |  |
| `max_targets_per_fire` | `integer \| null` | нет |  |
| `mode` | `string \| null` | нет |  |
| `name` | `string \| null` | нет |  |
| `params` | `object \| null` | нет |  |
| `selector` | `object \| null` | нет |  |
| `steps` | `массив string \| null` | нет |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `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

[Открыть отдельной страницей →](./post-runs-schedules-schedule-id-fire/)

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

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `schedule_id` | path | да | `integer` |  |
| `Idempotency-Key` | header | нет | `string` | Optional. |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `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

[Открыть отдельной страницей →](./get-runs-schedules-schedule-id-runs/)

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

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `schedule_id` | path | да | `integer` |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `массив integer` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Get Run

[Открыть отдельной страницей →](./get-runs-run-guid/)

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

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `run_guid` | path | да | `integer` |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `RunDetailResponse` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Cancel Run

[Открыть отдельной страницей →](./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.

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `run_guid` | path | да | `integer` |  |
| `Idempotency-Key` | header | нет | `string` | Optional. |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `PipelineRunRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `409` | The run is already terminal | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

_Пример ответа (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

[Открыть отдельной страницей →](./get-runs-run-guid-log/)

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

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `run_guid` | path | да | `integer` |  |
| `step` | query | нет | `string \| null` |  |
| `tail` | query | нет | `integer \| null` |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `RunLogResponse` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Retry Run

[Открыть отдельной страницей →](./post-runs-run-guid-retry/)

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

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `run_guid` | path | да | `integer` |  |
| `Idempotency-Key` | header | нет | `string` | Optional. |

**Тело запроса:** `application/json` — схема `RunRetryRequest`

| Поле | Тип | Обязательно | Описание |
| --- | --- | --- | --- |
| `from_step` | `string \| null` | нет |  |

_Пример:_

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

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `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` |

_Пример ответа (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

[Открыть отдельной страницей →](./get-runs-run-guid-steps/)

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

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `run_guid` | path | да | `integer` |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `массив RunStepRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |