Создавать, читать и менять бюджеты

Бюджет — это потолок того, что можно потратить. Каждый холд, который берёт вызов модели, проверяется по бюджетам, которые его покрывают, и вызов, который не помещается, отклоняется до обращения к провайдеру. Операции этой страницы перечисляют бюджеты с тем, что осталось от каждого, создают бюджет, меняют его лимит и отправляют его в архив. Консоль показывает те же бюджеты на Бюджеты.

Виды бюджетов

type говорит, что считает бюджет.

Денежный бюджет считает списанное и удержанное вместе, и холд, который вывел бы их за лимит, отклоняется с budget_exceeded. Статья Как работает резервирование бюджета объясняет холд.

Что покрывает бюджет

• scope, равный project, создаёт бюджет проекта ключа. organization создаёт бюджет всей организации, который считает траты каждого проекта.

• operation_code сужает бюджет до вызовов одной операции. Без него бюджет покрывает каждый вызов.

• type, scope и operation_code потом изменить нельзя: учтённые по ним траты за ними не последуют. Вместо этого создайте другой бюджет.

Ключ читает бюджеты своего проекта и бюджеты организации. Создаёт, меняет и отправляет в архив он только бюджеты своего проекта: запись в бюджет организации отвечает 403 с кодом project_access_restricted. Бюджет другого проекта или несуществующий отвечает 404 с кодом budget_not_found.

Кто может менять бюджет

Чтение требует разрешения read. Создание, изменение и отправка в архив требуют management:write: ключ, которым тратит приложение, — gateway:write, — читает бюджеты и не может их менять. Такой запрос отвечает 403 с кодом insufficient_scope. Журнал аудита записывает каждое создание, изменение и отправку в архив.

Изменить, отправить в архив и восстановить

• Новый limit_amount действует со следующего холда, в уже открытом окне. Лимит ниже того, что окно уже использовало, принимается: новый холд не помещается, пока окно не начнётся заново или лимит не поднимут.

• name — ваша собственная метка. null её стирает, а запрос без неё её сохраняет.

• Отправка в архив сохраняет бюджет и выводит его из новых холдов. Уже взятые холды всё равно рассчитываются. status, равный active, восстанавливает его.

• Список не показывает архивные бюджеты, если не отправить include_archived=1.

Изменение ждёт вызовы, которые в этот момент удерживают деньги по бюджету. Когда ожидание слишком долгое, оно отвечает 503 с кодом service_unavailable и заголовком Retry-After, и ничего не меняется. Отправьте тот же запрос снова.

События бюджета

Холд сообщает, насколько использован бюджет: budget.threshold_reached на 50 % и на 80 % лимита, budget.exceeded на всём лимите.

• О каждом уровне сообщается не больше раза за окно, а холд, который проходит два уровня сразу, сообщает только о более высоком.

• Бюджеты типов per_operation и concurrency таких событий не отправляют.

• Изменение лимита событий не отправляет. Лимит, опущенный ниже того, что окно использовало, не пропускает ни одного холда, поэтому budget.exceeded в этом окне для него не приходит. Поднятый лимит не сообщает заново об уровнях, о которых это окно уже сообщило.

Операции

{
  "data": [
    {
      "budget_id": "74438200973594624",
      "name": "string",
      "project_id": "74438200973594624",
      "type": "daily",
      "scope": "organization",
      "operation_code": "generate_email",
      "status": "active",
      "limit_amount": "0.02700000",
      "reserved_amount": "0.02700000",
      "captured_amount": "0.02700000",
      "available_amount": "0.02700000",
      "currency": "USD",
      "resets_at": "2026-10-02T09:30:00Z"
    }
  ]
}

{
  "type": "daily",
  "limit_amount": "0.02700000",
  "scope": "organization",
  "operation_code": "generate_email",
  "name": "string"
}

{
  "data": {
    "budget_id": "74438200973594624",
    "name": "string",
    "project_id": "74438200973594624",
    "type": "daily",
    "scope": "organization",
    "operation_code": "generate_email",
    "status": "active",
    "limit_amount": "0.02700000",
    "reserved_amount": "0.02700000",
    "captured_amount": "0.02700000",
    "available_amount": "0.02700000",
    "currency": "USD",
    "resets_at": "2026-10-02T09:30:00Z"
  }
}

{
  "limit_amount": "0.02700000",
  "status": "active",
  "name": "string"
}

{
  "data": {
    "budget_id": "74438200973594624",
    "name": "string",
    "project_id": "74438200973594624",
    "type": "daily",
    "scope": "organization",
    "operation_code": "generate_email",
    "status": "active",
    "limit_amount": "0.02700000",
    "reserved_amount": "0.02700000",
    "captured_amount": "0.02700000",
    "available_amount": "0.02700000",
    "currency": "USD",
    "resets_at": "2026-10-02T09:30:00Z"
  }
}

{
  "data": {
    "budget_id": "74438200973594624",
    "name": "string",
    "project_id": "74438200973594624",
    "type": "daily",
    "scope": "organization",
    "operation_code": "generate_email",
    "status": "active",
    "limit_amount": "0.02700000",
    "reserved_amount": "0.02700000",
    "captured_amount": "0.02700000",
    "available_amount": "0.02700000",
    "currency": "USD",
    "resets_at": "2026-10-02T09:30:00Z"
  }
}

Примеры

Получить список бюджетов

Месячный бюджет проекта использовал 432 из 500: 419,60 списано и 12,40 ещё удержано.

curl https://api.slen.ai/api/v1/budgets \
  -H "Authorization: Bearer $SLEN_API_KEY"

{
  "data": [
    {
      "budget_id": "74437302811459584",
      "name": "Production",
      "project_id": "74438200973594624",
      "type": "monthly",
      "scope": "project",
      "operation_code": null,
      "status": "active",
      "limit_amount": "500.00000000",
      "reserved_amount": "12.40000000",
      "captured_amount": "419.60000000",
      "available_amount": "68.00000000",
      "currency": "USD",
      "resets_at": "2026-11-01T00:00:00+00:00"
    },
    {
      "budget_id": "74437291503616000",
      "name": null,
      "project_id": null,
      "type": "total",
      "scope": "organization",
      "operation_code": null,
      "status": "active",
      "limit_amount": "10000.00000000",
      "reserved_amount": "12.40000000",
      "captured_amount": "2361.27500000",
      "available_amount": "7626.32500000",
      "currency": "USD",
      "resets_at": null
    }
  ]
}

Создать бюджет

Дневной бюджет одной операции в проекте ключа. Ответ уже говорит, когда кончается его окно.

curl https://api.slen.ai/api/v1/budgets \
  -H "Authorization: Bearer $SLEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "daily",
    "scope": "project",
    "operation_code": "generate_email",
    "limit_amount": "25",
    "name": "Follow-up emails"
  }'

{
  "data": {
    "budget_id": "74443127894704128",
    "name": "Follow-up emails",
    "project_id": "74438200973594624",
    "type": "daily",
    "scope": "project",
    "operation_code": "generate_email",
    "status": "active",
    "limit_amount": "25.00000000",
    "reserved_amount": "0.00000000",
    "captured_amount": "0.00000000",
    "available_amount": "25.00000000",
    "currency": "USD",
    "resets_at": "2026-10-03T00:00:00+00:00"
  }
}

Поднять лимит

Новый лимит действует со следующего холда. Удержанное и списанное остаются как были.

curl -X PATCH https://api.slen.ai/api/v1/budgets/74437302811459584 \
  -H "Authorization: Bearer $SLEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit_amount": "750"
  }'

{
  "data": {
    "budget_id": "74437302811459584",
    "name": "Production",
    "project_id": "74438200973594624",
    "type": "monthly",
    "scope": "project",
    "operation_code": null,
    "status": "active",
    "limit_amount": "750.00000000",
    "reserved_amount": "12.40000000",
    "captured_amount": "419.60000000",
    "available_amount": "318.00000000",
    "currency": "USD",
    "resets_at": "2026-11-01T00:00:00+00:00"
  }
}

Отправить бюджет в архив

Ответ — бюджет со status, равным archived.

curl -X DELETE https://api.slen.ai/api/v1/budgets/74443127894704128 \
  -H "Authorization: Bearer $SLEN_API_KEY"

{
  "data": {
    "budget_id": "74443127894704128",
    "name": "Follow-up emails",
    "project_id": "74438200973594624",
    "type": "daily",
    "scope": "project",
    "operation_code": "generate_email",
    "status": "archived",
    "limit_amount": "25.00000000",
    "reserved_amount": "0.00000000",
    "captured_amount": "0.00000000",
    "available_amount": "25.00000000",
    "currency": "USD",
    "resets_at": "2026-10-03T00:00:00+00:00"
  }
}

Что читать дальше

• Бюджеты — те же бюджеты в консоли.

• Как работает резервирование бюджета — что такое холд и как он рассчитывается.

• Вебхуки — как приходят события бюджета.