Budgets

A budget is checked before the gateway routes a request, so an exhausted budget costs you nothing. Set one when a runaway loop or a shared key could otherwise spend real money against an upstream provider.

What you can cap

Every cap is optional and null means no cap. Money is EUR micros throughout: 1,000,000 micros is €1, so a €50 monthly ceiling is maxCostMicros: 50000000.

Periods run in UTC. A day budget resets at midnight UTC, a month budget on the first of the month.

Scope

A budget applies to a request when its applicationId and userId are either unset or match. Leaving both unset gives an organization-wide budget; setting applicationId narrows it to one application; setting userId narrows it to one member. Combining the two is allowed, and several budgets can match the same request, in which case all of them are checked.

In the console, /[org]/ai-gateway/budgets edits organization budgets while the same page inside an application edits only that application's, leaving budgets belonging to other scopes untouched when you save. Per-user budgets and maxRequestCostMicros have no field in the console; set those through the API or the CLI.

Setting budgets

Writing budgets replaces the organization's whole set in one transaction. Send every budget you want to keep, and send an empty array to clear them all. Writes need the network:ai_gateway:budgets:write scope, and a user acting on their own behalf must be an owner or admin. Signing in with gigadrive login does not grant that scope, so the following CLI examples want an organization API key in GIGADRIVE_CLIENT_ID and GIGADRIVE_CLIENT_SECRET.

import { GigadriveClient } from '@gigadrive/sdk';

const client = new GigadriveClient({
  clientId: process.env.GIGADRIVE_CLIENT_ID,
  clientSecret: process.env.GIGADRIVE_CLIENT_SECRET,
});

const organizationId = '0197b2f0-8b6d-7c2a-9f4e-111111111111';

await client.organizations.aiGateway.budgets.replace(organizationId, [
  // €50 a month across the whole organization
  { period: 'month', maxCostMicros: 50_000_000, enabled: true },
  // 10,000 requests a day for one application, and no single request above €0.25
  {
    period: 'day',
    applicationId: '0195c11c-0000-7000-8000-000000000042',
    maxRequests: 10_000,
    maxRequestCostMicros: 250_000,
    enabled: true,
  },
]);

const { items } = await client.organizations.aiGateway.budgets.list(organizationId);

When a budget is reached

The request is refused with HTTP 429, "type": "insufficient_quota", and a code naming the cap that stopped it: budget_requests_exceeded, budget_tokens_exceeded, budget_cost_exceeded or budget_request_cost_exceeded. Budgets are checked in sequence and the first exhausted one wins, so the code tells you which limit to raise. Nothing is queued and nothing is retried; the next period clears it.

What counts toward a budget is deliberate. Successful requests count, and in-flight requests count toward maxRequests while contributing nothing to the token and cost totals until they finish. Requests that error or are cancelled count toward nothing.

maxRequestCostMicros is different from the others: it is enforced before routing, against an upper-bound estimate of what the request could cost, priced against the most expensive eligible provider. A request whose estimate exceeds the cap never reaches a provider. If the finished request turns out to cost more than the cap anyway, that is logged and left alone rather than blocked after the fact.