API: runs

Статус: GA Доступ: по токену контракт API: 0.3.0 · capability 2026-09-03.1 Открыть как Markdown Открыть в Claude Открыть в ChatGPT

`GET /api/v1/runs`

List 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

Открыть отдельной страницей →

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`	нет

Пример:

{
  "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):

{
  "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

Открыть отдельной страницей →

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

Открыть отдельной страницей →

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

Открыть отдельной страницей →

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

Открыть отдельной страницей →

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

Открыть отдельной страницей →

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

Открыть отдельной страницей →

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

Открыть отдельной страницей →

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

Открыть отдельной страницей →

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

Открыть отдельной страницей →

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

Открыть отдельной страницей →

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

Открыть отдельной страницей →

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):

{
  "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

Открыть отдельной страницей →

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

Открыть отдельной страницей →

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`	нет

Пример:

{
  "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):

{
  "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

Открыть отдельной страницей →

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`