ProxyAPI записывает информацию о каждом запросе к API в виде транзакций — вы видите модель, количество токенов и списанную сумму. Однако этих данных недостаточно для полноценной отладки: нет статус-кодов, задержек, ошибок провайдера и, главное, — содержимого запросов и ответов.
Логирование запросов решает эту проблему. При включении сервис записывает полные данные о каждом обращении к API: метаданные (статус, задержка, модель, ключ), потребление (токены с разбивкой по типам), а также полное содержимое запросов и ответов — включая промпты, ответы модели и сообщения об ошибках.
Логируются не только успешные запросы, но и отклонённые на уровне прокси — превышение лимита, недостаточный баланс, превышение бюджета ключа. Это позволяет увидеть полную картину: почему часть запросов не доходит до провайдера.
- Перейдите в раздел Логи в боковом меню личного кабинета
- Нажмите Включить логирование
- Выберите период хранения (3, 7, 30 или 365 дней)
- Подтвердите активацию
Логирование действует на уровне аккаунта — записываются запросы по всем API-ключам. Новые запросы начнут логироваться сразу после активации.
Историческая информация после активации не переносится в логи — записи накапливаются с момента включения.
Каждый запрос к API ProxyAPI возвращает заголовок X-Request-ID с уникальным идентификатором (UUID):
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
Этот идентификатор можно использовать для:
- Поиска в логах — в фильтрах на странице Логи есть поле «Request ID»
- Обращения в поддержку — передайте Request ID, чтобы мы могли быстро найти информацию о запросе
Вы можете прикреплять произвольные метаданные к каждому запросу с помощью HTTP-заголовков с префиксом X-Log-. Метаданные сохраняются в логе и доступны в детальном просмотре и экспорте.
Префикс X-Log- удаляется, остаток приводится к нижнему регистру:
X-Log-Session: abc123 → session: abc123 X-Log-Environment: staging → environment: staging X-Log-Tag: experiment-42 → tag: experiment-42
Пример запроса с метаданными:
curl https://api.proxyapi.ru/openai/v1/chat/completions \ -H "Authorization: Bearer sk-..." \ -H "X-Log-Session: abc123" \ -H "X-Log-Environment: production" \ -H "Content-Type: application/json" \ -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Привет"}]}'
- Не более 10 заголовков
X-Log-*на запрос - Длина ключа (после удаления префикса) — не более 64 символов
- Длина значения — не более 256 символов
Заголовки, превышающие лимиты, молча игнорируются — запрос никогда не отклоняется из-за метаданных.
Фильтрация по метаданным пока не поддерживается — они доступны только при просмотре отдельной записи и в экспорте.
Каждая запись в логах имеет один из четырёх статусов:
| Статус | Описание |
|---|---|
success | Запрос отправлен провайдеру, получен успешный ответ |
provider_error | Запрос отправлен провайдеру, получена ошибка (4xx/5xx) |
provider_timeout | Запрос отправлен провайдеру, соединение оборвалось или истекло время ожидания |
proxy_error | Запрос отклонён на стороне ProxyAPI (rate limit, недостаточный баланс, превышение бюджета и т.д.) |
- Идентификация: API-ключ (название и маскированный), модель, провайдер, endpoint, IP-адрес клиента
- Производительность: HTTP-код ответа, общая задержка (мс), время до первого токена (для стриминга), флаг стриминга
- Потребление: разбивка по типам токенов (ввод, вывод, размышления, кэш и др.), размер запроса и ответа в байтах
- Биллинг: списанная сумма (для отклонённых запросов — пусто, так как списания не происходит)
- Ошибки: тип и текст ошибки (от провайдера или от ProxyAPI)
- Содержимое запросов и ответов: промпт, ответ модели или сообщение об ошибке
- Пользовательские метаданные: произвольные данные, переданные через заголовки
X-Log-*(см. ниже)
Для запросов, отклонённых на уровне ProxyAPI (proxy_error): нет ответа от провайдера, нет потребления токенов, задержка отражает время обработки на стороне ProxyAPI. Содержимое ответа — наше сообщение об ошибке.
Стоимость логирования зависит от выбранного периода хранения:
| Период хранения | Стоимость за 1 000 запросов | Бесплатный лимит |
|---|---|---|
| 3 дня | 8 ₽ | 10 000 запросов/мес |
| 7 дней | 10 ₽ | — |
| 30 дней | 12 ₽ | — |
| 365 дней | 15 ₽ | — |
На тарифе с хранением 3 дня первые 10 000 запросов в месяц — бесплатно. После исчерпания лимита запросы продолжают логироваться и оплачиваются по стандартной ставке 8 ₽ за 1 000 запросов. Счётчик обнуляется в начале каждого месяца.
При переходе на любой другой период хранения (7, 30, 365 дней) оплата начинается с первого запроса.
- Списание происходит с вашего баланса ProxyAPI — того же, с которого оплачиваются запросы к моделям
- Биллинг — ежедневный: каждую ночь в 04:00 МСК начисляется оплата за запросы предыдущего дня по текущему тарифу
- Смена тарифа влияет только на будущие списания — пересчёта за прошлые дни не происходит
Период хранения — это скользящее окно: хранятся все логи за последние N дней. Очистка устаревших записей выполняется автоматически каждую ночь.
При увеличении периода хранения существующие логи будут храниться дольше.
При уменьшении периода хранения записи за пределами нового окна будут удалены в ближайшую ночную очистку (04:00 МСК). До этого момента можно отменить изменение.
При отключении логирования:
- Новые запросы сразу перестают логироваться
- Существующие логи остаются доступны до 04:00 МСК — у вас есть время экспортировать данные
- В 04:00 МСК: начисляется оплата за последние запросы, затем все логи удаляются
Если вы передумали — включите логирование обратно до 04:00 МСК, и все существующие логи сохранятся, запись возобновится.
Экспорт позволяет скачать логи в машиночитаемом формате для внешнего анализа или архивирования.
- На странице Логи нажмите кнопку экспорта (иконка скачивания)
- Выберите вариант включения содержимого запросов/ответов (см. ниже)
- Нажмите Экспортировать
- Ссылка на скачивание придёт на вашу почту (действует 24 часа)
Экспорт выгружает все логи за выбранный на странице диапазон дат и времени (или за всё время, если диапазон не указан).
| Вариант | Описание |
|---|---|
| Без содержимого | Только метаданные — самый быстрый и компактный |
| С содержимым (без крупного) | Включает содержимое запросов и ответов до 128 КБ; крупное содержимое (изображения, аудио) — пропускается |
| С содержимым (все) | Всё содержимое, включая крупное — оно помещается в папку payloads/ внутри архива |
Экспорт — zip-архив, содержащий:
logs.ndjson— по одной JSON-строке на каждую записьpayloads/— папка с крупным содержимым запросов и ответов (только при выборе варианта «все»)
- Не более 10 экспортов в сутки
- Только один экспорт одновременно — дождитесь завершения текущего
Каждая строка в файле logs.ndjson — это JSON-объект со следующими полями:
| Поле | Тип | Описание |
|---|---|---|
id | string (UUID) | Уникальный идентификатор запроса. Совпадает со значением заголовка X-Request-ID |
created_at | string (ISO 8601) | Время получения запроса |
client_ip | string | IP-адрес клиента, отправившего запрос |
model | string | Название модели (например, gpt-4o, claude-3.5-sonnet) |
snapshot | string | Точная версия модели, использованная провайдером (например, gpt-4o-2024-08-06) |
provider | string | Провайдер: openai, anthropic, google, openrouter |
endpoint | string | Путь запроса, включая query-параметры (например, /openai/v1/chat/completions) |
api_key_name | string | Название API-ключа |
api_key_masked | string | Маскированный API-ключ (например, sk-...a1b2) |
status | string | Статус: success, provider_error, provider_timeout, proxy_error |
status_code | integer | HTTP-код ответа, возвращённый клиенту (включая коды ProxyAPI: 429, 402, 400) |
latency_ms | integer | Общая задержка в миллисекундах |
ttft_ms | integer / null | Время до первого токена в миллисекундах. Только для стриминговых запросов, иначе null |
is_streaming | boolean | Был ли запрос стриминговым |
request_bytes | integer | Размер содержимого запроса в байтах |
response_bytes | integer | Размер содержимого ответа в байтах |
amount | string / null | Списанная сумма в рублях (строка с десятичным числом). null для запросов, отклонённых на стороне ProxyAPI |
vat | integer | Процент НДС, включённый в сумму |
error_type | string | Тип ошибки. Пустая строка при успешном запросе |
error_message | string | Текст ошибки. Пустая строка при успешном запросе |
usage_breakdown | array | Разбивка потребления (см. ниже) |
meta | object | Метаданные записи. Содержит custom — объект с пользовательскими метаданными из заголовков X-Log-* (если были переданы) |
request_body | string / null | Содержимое запроса (JSON-строка). Присутствует при выборе варианта «с содержимым». null для крупного содержимого при варианте «без крупного» |
response_body | string / null | Содержимое ответа (JSON-строка). Присутствует при выборе варианта «с содержимым». null для крупного содержимого при варианте «без крупного» |
request_body_file | string / null | Путь к файлу содержимого запроса внутри архива (например, payloads/550e8400_req.json). Только для крупного содержимого при варианте «все» |
response_body_file | string / null | Путь к файлу содержимого ответа внутри архива. Только для крупного содержимого при варианте «все» |
Массив объектов, описывающих потребление ресурсов в рамках запроса. Один запрос может содержать несколько элементов — например, при использовании модели с веб-поиском будет отдельная запись на потребление модели и отдельная на веб-поиск.
Каждый элемент имеет три поля:
type— тип продукта:MODEL_TEXT,MODEL_IMAGE,MODEL_VIDEO,MODEL_TTS,MODEL_STT,MODEL_EMBEDDING,SERVICEproduct— строка видапровайдер/продукт/снапшот(например,openai/gpt-4o/gpt-4o-2024-08-06) илипровайдер/продуктдля сервисных продуктов (например,openai/web-search)breakdown— объект с парами «тип потребления → количество»
Пример:
[ { "type": "MODEL_TEXT", "product": "openai/gpt-4o/gpt-4o-2024-08-06", "breakdown": { "input_tokens": 150, "output_tokens": 420, "reasoning_tokens": 100 } }, { "type": "SERVICE", "product": "openai/web-search", "breakdown": { "web_search": 1 } } ]
| Ключ | Описание |
|---|---|
input_tokens | Токены ввода (промпт, контекст) |
output_tokens | Токены вывода (ответ модели) |
reasoning_tokens | Токены размышлений (когда тарицифируются отдельно от токенов вывода) |
cached_read_tokens | Токены, прочитанные из кэша провайдера |
cached_write_tokens | Токены, записанные в кэш провайдера |
audio_input_tokens | Аудио-токены ввода |
audio_output_tokens | Аудио-токены вывода |
images | Количество сгенерированных изображений |
web_search | Количество операций веб-поиска |
sessions | Количество сессий (Code interpreter и др.) |
characters | Количество символов (синтез речи) |
На данный момент не логируются:
- Запросы через OpenAI-совместимый API
- Запросы к API, включенных в подписку OpenAI Pro (Assistants API, Files API, и т.д.)
- Запросы на генерацию видео (Sora, Veo)
- Некоторые клиентские ошибки валидации (неизвестная модель, некорректное содержимое запроса), которые отклоняются до начала обработки запроса — такие ошибки не попадают в логи
Логирование действует на уровне аккаунта. Включение логирования для отдельных API-ключей пока не поддерживается.
