Получить результат

Три способа узнать, что прогон завершился — от простого к масштабируемому.

1. Синхронное ожидание (?wait=60)Скопировать ссылку

Самый простой способ для одиночных запросов: параметр wait (0–60 секунд) у POST /v1/extract и POST /v1/typizers/{id}/runs держит запрос открытым до завершения прогона или до истечения времени:

• прогон успел завершиться в срок — ответ 200 с готовым результатом;
• не успел — ответ 202 с текущим состоянием прогона (queued/processing); продолжайте опросом или вебхуком, как показано ниже.

Подходит, пока вы обрабатываете документы по одному и готовы недолго держать соединение открытым. Для большого количества документов — пакетная обработка («Пакетная обработка») и вебхук, а не долгий цикл wait.

2. Опрос GET /v1/runs/{id}Скопировать ссылку

Создайте прогон без wait (или с коротким) и опрашивайте его статус отдельными запросами:

curl https://api.typizer.ru/v1/runs/$RUN_ID \
  -H "Authorization: Bearer $TYPIZER_API_KEY"

Поле status — queued, processing, succeeded или failed. Пока прогон не завершён, опрашивайте не чаще раза в несколько секунд — частый опрос только расходует ваш лимит запросов («Лимиты») и не ускоряет обработку.

3. ВебхукСкопировать ссылку

Самый экономный по запросам способ — не опрашивать вообще, а подписаться на событие run.succeeded/run.failed и получить уведомление, когда прогон завершится. Подробности настройки и проверки подписи — «Приём вебхуков».

Постраничный вывод списковСкопировать ссылку

Списки (GET /v1/runs, /v1/batches, /v1/webhook_endpoints и другие) используют единый формат постраничного вывода:

{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "run_…" }

• limit — размер страницы в запросе (1–100, по умолчанию 20);
• has_more — есть ли ещё данные после этой страницы;
• next_cursor — идентификатор последнего элемента страницы; передайте его следующим запросом как starting_after, чтобы получить продолжение:

curl "https://api.typizer.ru/v1/runs?limit=50&starting_after=$NEXT_CURSOR" \
  -H "Authorization: Bearer $TYPIZER_API_KEY"

Повторяйте, пока has_more не станет false.

Исключение: GET /v1/usageСкопировать ссылку

GET /v1/usage устроен иначе — это не список записей с курсором, а агрегат по дням, типизаторам или ключам за диапазон дат (group_by). Его has_more означает другое: групп получилось больше 1000, и в data остались только самые крупные по списанным страницам — starting_after тут не применяется, вместо этого сузьте диапазон from/to или смените group_by.

Что дальшеСкопировать ссылку

• «Приём вебхуков» — настройка конечной точки и проверка подписи.
• «Пакетная обработка» — обработка сразу многих документов.
• «Лимиты» — частота запросов при опросе.