# Свои запросы

`GET https://api.souz.ai/v1/usage`

Страница истории запросов, новые первыми; фильтры и страницы — на сервере. since ограничивает период снизу, status, modality, model и api_key_id оставляют одно значение, q — точный id запроса (job_…, chatcmpl-…) или ключ идемпотентности; фильтры действуют вместе. Модель без запросов, чужой или несуществующий ключ — пустая страница, а не ошибка. Страницы — по курсору: next_before из ответа передаётся в before, пока он не станет null. Разработчик видит только запросы по выданным ему ключам (включая его ключ плейграунда), остальные роли — все запросы аккаунта. Итоги и график периода — GET /v1/usage/summary.

## Авторизация

- `ManagementKey`: Ключ управления из кабинета souz.ai (выдают владелец и администратор аккаунта — себе или участнику). Даёт ровно то, что его держатель видит и может в кабинете: баланс, историю операций и запросов, расходы, обычные ключи, настройки аккаунта — с той же ролью, лимитами и цифрами. Модели не запускает. Обычный API-ключ здесь не подходит: `403 forbidden` с `detail[].reason: requires_management_key`.
- `ClientSession`: Сессия кабинета souz.ai в браузере — те же ручки, что у ключа управления.

## Параметры

| Имя | Где | Обязательно | Тип | Описание |
|---|---|---|---|---|
| `limit` | query | нет | `integer` | По умолчанию 100, максимум 1000 |
| `since` | query | нет | `string, date-time` | Нижняя граница периода, RFC3339 |
| `before` | query | нет | `string` | Курсор next_before предыдущей страницы |
| `status` | query | нет | схема `UsageStatus` | Только запросы в этом статусе |
| `modality` | query | нет | схема `Modality` | Только запросы этой модальности |
| `model` | query | нет | `string` | Только запросы к этой модели — её id, как canonical_model у строки истории |
| `api_key_id` | query | нет | `string` | Только запросы по этому ключу — его id (key_…), как api_key_id у строки истории |
| `q` | query | нет | `string` | Точный id запроса (job_…, chatcmpl-…) или ключ идемпотентности |
| `source` | query | нет | `string`; значения: `playground` | Только запросы из плейграунда (ключом плейграунда) |

## Пример запроса

```bash
curl -X GET 'https://api.souz.ai/v1/usage' \
  -H "Authorization: Bearer $SOUZ_MANAGEMENT_KEY"
```

```python
import os
import requests

response = requests.get(
    "https://api.souz.ai/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_MANAGEMENT_KEY']}"},
)
print(response.json())
```

```ts
const response = await fetch("https://api.souz.ai/v1/usage", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.SOUZ_MANAGEMENT_KEY}` },
});
console.log(await response.json());
```

## Ответы

### 200

OK

- `application/json`, схема `UsageResponse`

### 400

Запрос отклонён; `error.detail[]` называет поля и допустимые значения.

- `application/json`, схема `Error`

```json
{
  "error": {
    "code": "capability_mismatch",
    "detail": [
      {
        "allowed": [
          "1:1",
          "16:9",
          "9:16"
        ],
        "path": "aspect_ratio",
        "reason": "unsupported_value"
      }
    ],
    "message": "the model does not support this value",
    "type": "invalid_request_error"
  }
}
```

### 401

Нет ключа или ключ недействителен.

- `application/json`, схема `Error`

### 403

Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли участника нет права или подпись ссылки на файл не сходится. `detail[].reason` говорит, что именно: `requires_api_key`, `requires_management_key`, `cabinet_only` (только в кабинете), `insufficient_role` (в `allowed` — роли, которым можно), `not_key_author` (секрет ключа открывает только тот, кто его создал).

- `application/json`, схема `Error`

```json
{
  "error": {
    "code": "forbidden",
    "detail": [
      {
        "reason": "requires_api_key"
      }
    ],
    "message": "this endpoint takes an API key; a management key manages the account only",
    "type": "permission_error"
  }
}
```

### 429

Слишком часто — повторите через `Retry-After` секунд. Запуск моделей, задачи и файлы результатов частотой не ограничены (их ограничивают баланс и лимиты трат); здесь 429 — на поток запросов с ключом, который сервер не знает, с одного адреса, и на потоки сверх 1000 одновременных на аккаунт (события задачи, чат с `stream: true`). Пределы — раздел «Лимиты» руководства.

- `application/json`, схема `Error`

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.