## Журнал запусков

`GET /v1/infra/servers/:id/jobs/:jobId/runs`

Возвращает журнал одной неудалённой задачи, от новых к старым по scheduledFor и id. Работает при недоступности функции. Секрет отсутствует; журнал и фрагменты ответа доступны только через серверные права.

Нужен ключ с `vibe:infra` и существующие права на сервер. Для записи — управляющий ключ или роль команды с правом управления жизненным циклом. [Общие правила](../jobs.md); [проверка подписи](./signature.md).

## Параметры

| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
| `id` | path | string | yes | ID сервера из [списка серверов](../servers.md) |
| `jobId` | path | string | yes | ID задачи из [списка](./list.md) |
| `cursor` | query | string | no | Непрозрачный nextCursor предыдущей страницы; не конструируйте вручную |
| `limit` | query | integer | no | По умолчанию 50, от 1 до 100 |

## Примеры

### curl — личный ключ

```bash
curl --max-time 20 -X GET "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/jobs/JOB_ID/runs?limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl --max-time 20 -X GET "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/jobs/JOB_ID/runs?limit=50" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const serverId = 'SERVER_ID';
const jobId = 'JOB_ID';
const res = await fetch(`https://vibecode.bitrix24.tech/v1/infra/servers/${encodeURIComponent(serverId)}/jobs/${encodeURIComponent(jobId)}/runs?limit=50`, {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
});
const result = await res.json();
if (!res.ok || !result.success) throw new Error(result.error?.code ?? `HTTP_${res.status}`);
console.log(result);
```

### JavaScript — OAuth-приложение

```javascript
const serverId = 'SERVER_ID';
const jobId = 'JOB_ID';
const res = await fetch(`https://vibecode.bitrix24.tech/v1/infra/servers/${encodeURIComponent(serverId)}/jobs/${encodeURIComponent(jobId)}/runs?limit=50`, {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
});
const result = await res.json();
if (!res.ok || !result.success) throw new Error(result.error?.code ?? `HTTP_${res.status}`);
console.log(result);
```

## Ответ

HTTP 200. Пример формы ответа с вымышленными идентификаторами, не результат живого запроса.

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "run_example",
        "jobId": "job_example",
        "serverId": "server_example",
        "portalId": "account_example",
        "path": "/tasks/digest?mode=daily",
        "scheduleRevision": 1,
        "trigger": "SCHEDULE",
        "scheduledFor": "2026-10-10T06:00:00.000Z",
        "status": "SUCCEEDED",
        "attempts": 1,
        "nextAttemptAt": null,
        "readyDeadlineAt": "2026-10-10T06:30:00.000Z",
        "deliveryDeadlineAt": "2026-10-14T06:00:00.000Z",
        "waitingForServer": false,
        "startedAt": "2026-10-10T06:00:02.000Z",
        "lastAttemptStartedAt": "2026-10-10T06:00:02.000Z",
        "late": false,
        "finishedAt": "2026-10-10T06:00:02.150Z",
        "durationMs": 150,
        "responseSource": "app",
        "httpStatus": 202,
        "errorCode": null,
        "lastAttemptErrorCode": null,
        "requestId": "request_example",
        "responseSnippet": "{\"accepted\":true}",
        "createdAt": "2026-10-10T06:00:00.000Z",
        "updatedAt": "2026-10-10T06:00:02.150Z"
      }
    ],
    "nextCursor": null
  }
}
```

## Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `success` | boolean | Всегда `true` при успехе. |
| `data` | object | Объект со страницей запусков в `items` и курсором `nextCursor`. |

Секрет подписи в ответе отсутствует.

Поля объекта `data`:

| Поле | Тип | Описание |
|---|---|---|
| `items` | array | Запуски этой страницы |
| `nextCursor` | string / null | Передайте как cursor; null — конец |

Поля каждого запуска в `data.items`:

| Поле | Тип | Описание |
|---|---|---|
| `id` | string | Идентификатор запуска; это runId в доставленном теле |
| `jobId` | string | Идентификатор задачи |
| `serverId` | string | Идентификатор сервера |
| `portalId` | string / null | Снимок портала при создании запуска |
| `path` | string | Снимок пути; PATCH не меняет уже созданный запуск |
| `scheduleRevision` | integer | Снимок ревизии расписания |
| `trigger` | string | SCHEDULE или MANUAL; в HTTP-теле значения в нижнем регистре |
| `scheduledFor` | string | Плановое время либо время создания ручного запуска, UTC ISO-8601 |
| `status` | string | Текущее состояние из таблицы ниже |
| `attempts` | integer | Число зарезервированных попыток доставки, 0–4 |
| `nextAttemptAt` | string / null | Срок следующей проверки или повтора у PENDING; иначе null |
| `readyDeadlineAt` | string | createdAt + 30 минут, фиксированный срок готовности |
| `deliveryDeadlineAt` | string | createdAt + 96 часов, предел жизни доставки PENDING |
| `waitingForServer` | boolean | Сервер пока не подтвердил готовность |
| `startedAt` | string / null | Начало первой попытки, не доказательство приёма приложением |
| `lastAttemptStartedAt` | string / null | Начало последней попытки |
| `late` | boolean | Первая попытка началась позже scheduledFor + 60 секунд; значение сохранено на все повторы |
| `finishedAt` | string / null | Время окончательного исхода, UTC ISO-8601 |
| `durationMs` | integer / null | Продолжительность последней попытки в миллисекундах |
| `responseSource` | string / null | app, gateway или null; app не доказывает выполнение обработчика |
| `httpStatus` | integer / null | HTTP-статус ответа приложения, если есть |
| `errorCode` | string / null | Итоговый код причины |
| `lastAttemptErrorCode` | string / null | Причина последней неуспешной попытки; сохраняется при административной отмене |
| `requestId` | string / null | Идентификатор запроса канала доставки, если есть |
| `responseSnippet` | string / null | Ограниченный фрагмент ответа приложения, только авторизованному читателю |
| `createdAt` | string | Время создания, UTC ISO-8601 |
| `updatedAt` | string | Время последнего изменения, UTC ISO-8601 |

### Состояния и причины

`PENDING` — очередь или ожидание; `RUNNING` — отправляемая попытка. Остальные состояния окончательные: `SUCCEEDED` (HTTP 2xx), `FAILED`, `SKIPPED_BILLING`, `SKIPPED_ACCESS`, `SUPERSEDED`, `SERVER_UNAVAILABLE`. SUCCEEDED не означает окончания фоновой работы. startedAt не доказывает приём обработчиком.

| Код | Значение |
|---|---|
| `JOB_DISABLED` | Плановая задача выключена до отправки |
| `SCHEDULE_CHANGED` | Ревизия планового запуска устарела |
| `JOB_DELETED` | Задача удалена до отправки |
| `ENTITLEMENT_REVOKED` | Утрачен допуск к расписаниям |
| `FEATURE_DISABLED` | Функция отключена до отправки |
| `RUN_EXPIRED` | Истекли 96 часов жизни доставки |
| `TARGET_BINDING_CHANGED` | Портал сервера изменился после создания запуска |
| `READY_DEADLINE_EXCEEDED` | Не подтверждена готовность до срока 30 минут |
| `ATTEMPTS_EXHAUSTED` | Исчерпаны четыре попытки; причину смотрите в lastAttemptErrorCode |
| `NEWER_SCHEDULE` | Более новое плановое вхождение вытеснило ещё не отправленный запуск |

Отсутствующий или сменившийся портал и отказ оплаты/доступа имеют приоритет над административной отменой; затем проверяется срок ожидания готовности, удаление/выключение/ревизия, допуск, доступность функции, 96-часовой срок и бюджет попыток; вытеснение новым расписанием — последним. MANUAL не отменяется только из-за enabled=false или изменения cron/timezone. RUNNING доживает до исхода своей попытки.

### Повторы

HTTP 2xx успешен; 3xx окончательный отказ без перехода по редиректу; 4xx, включая 408, окончательный отказ, кроме 429. Для 429 и 5xx возможен повтор. Четыре попытки максимум; после первых трёх — случайная задержка от 1 мс до 1, 5 и 15 минут соответственно. Корректный Retry-After (секунды или HTTP-date) увеличивает задержку; срок более 24 часов завершает запуск с RETRY_AFTER_TOO_LONG. Срок повтора не выходит за deliveryDeadlineAt: на границе RUN_EXPIRED, а не новая отправка.

Временные причины: `BH_TUNNEL_DISCONNECTED`, `BH_APP_STARTING`, `BH_APP_TIMEOUT`, `BH_APP_TRUNCATED`, `BH_APP_BUDGET_EXHAUSTED`, `BUDGET_EXHAUSTED`, `PORTAL_SATURATED`, `GATEWAY_SATURATED`, `TIMEOUT`, `TRANSPORT`, `LEASE_EXPIRED`. Окончательные причины: `BH_APP_RESPONSE_TOO_LARGE`, `RESPONSE_TOO_LARGE`, `BAD_ENVELOPE`, `UNKNOWN_GATEWAY_CODE`, `UNKNOWN_FORWARD_ERROR`, `INTERNAL_ERROR`, `HTTP_3XX`, `HTTP_4XX`. Для `HTTP_429`/`HTTP_5XX` также возможен повтор. При `ATTEMPTS_EXHAUSTED` исходная причина остаётся в `lastAttemptErrorCode`.

## Ошибки

| HTTP | Код | Причина |
|---|---|---|
| 401 | `MISSING_API_KEY` | Не передан ключ |
| 403 | `SERVER_ROLE_FORBIDDEN` | Роль участника команды не допускает это действие |
| 404 | `NOT_FOUND` | Сервер не найден или недоступен вызывающему |
| 404 | `NOT_FOUND` | Задача отсутствует, удалена или принадлежит другому серверу |
| 400 | `INVALID_CURSOR` | Неверный или неизвестный cursor |
| 400 | `INVALID_LIMIT` | limit должен быть целым числом от 1 до 100 |

Полный список общих ошибок API — [Ошибки](/docs/errors).

```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Job not found"
  }
}
```

## Смотрите также

- [Список задач](./list.md)
- [Запустить вручную](./run.md)