Перейти к содержанию
Sursa для разработчиков

GET/v1/api-usage

Получить использование API

get_api_usage

Возвращает запросы, сделанные ключами API организации, по ключам и шагам периода: число запросов, ошибок (ответы 4xx и 5xx) и задержка p50 и p95. Шаг day охватывает до 400 дней, по умолчанию последние 30, а запросы и ошибки — точные счётчики. Шаг hour охватывает до 14 дней, по умолчанию последние 24 часа; его значения берутся из журнала запросов API и сверх дневного лимита журнала оцениваются по выборке. Задержка берётся из журнала запросов API за последние 14 дней. Отказы ограничителя частоты и квоты (api.rate_limited, api.quota_exceeded) не считаются. Шаги без запросов не включаются. Ключ API, ограниченный коллекциями (collection_ids), видит только своё использование и использование ключей, которые он видит в GET /v1/api-keys. Нужно право ORG_MANAGE_KEYS; ключу API нужны роль администратора и область admin. Добавлено в 1.62.0.

Аутентификация

Передайте ключ API в заголовке Authorization: Authorization: Bearer <ключ>.

Параметры запроса

  • granularitystring

    Шаг ряда: день или час по UTC.

    Допустимые значения: dayhour

    По умолчанию: "day"

  • sincestring (date-time)

    Начало периода (включительно), RFC 3339 со смещением; округляется вниз до начала шага.

  • untilstring (date-time)

    Конец периода (не включительно), RFC 3339 со смещением; по умолчанию — текущий момент.

  • key_idinteger

    Только этот ключ API организации.

    ≥ 1

Ответы

200Успешный ответ

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: ApiUsage

  • granularitystringобязательно

    Шаг ряда.

    Допустимые значения: dayhour

  • sincestring (date-time)обязательно

    Начало периода: начало первого шага (UTC).

  • untilstring (date-time)обязательно

    Конец периода, не включительно (UTC).

  • dataarray of ApiUsagePointобязательно

    Шаги с запросами по возрастанию времени, внутри шага — по ключам.

401Учётные данные не переданы (нет ни cookie сессии, ни ключа API) или ключ не найден.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

403Действие запрещено: недостаточно прав роли, нет доступа к коллекции или карточке, запрос выполняется в режиме «Смотреть как» либо организация приостановлена или удалена (`detail` — объект с `code: org_suspended | org_deleted`).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

422Ошибка проверки: тело или параметры не соответствуют схеме (`detail` — список ошибок проверки) либо значение параметра вне допустимого диапазона (`detail` — сообщение).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

429Слишком много запросов (`api.rate_limited`), квота организации на минуту, день или месяц исчерпана (`api.quota_exceeded`; в `error.details` — `quota`, `limit` и `reset_at`), достигнут лимит организации или сервис ответов занят (`answers.engine_busy`). Подождите время, указанное в заголовке `Retry-After`.

Заголовки ответа

  • Retry-After

    Сколько секунд подождать перед повтором запроса.

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

Коды ошибок

Коды, которые эта операция может вернуть в error.code, помимо общих кодов любого запроса.

Лимиты частоты

В ответах есть заголовки RateLimit и RateLimit-Policy, а также прежние X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. В ответе 429 есть Retry-After в секундах: подождите и повторите запрос.

← api-keys · Справочник API