How to set a credit limit on an OpenRouter API key

Setting a key credit limit in the dashboard

When you create an API key in the OpenRouter dashboard, the interface prompts you for a label and gives you the option to choose a credit limit or no limit. It's easy to overlook that second box when you're in a hurry to test a prompt.

Don't skip it.

An unlimited key exposes your entire balance. If you deploy an experimental agent loop that gets stuck or push code containing a raw credential to a public repository, an unlimited key will spend until your account runs completely dry. If you've enabled automated balance top-ups, it'll keep charging your payment method until the underlying card declines. If you suspect an exposure has already occurred, review What should I do in the first hour after an API key leaks? to contain the damage immediately.

Once a key reaches its credit limit, OpenRouter rejects further calls made with it. Traffic stops until you manually increase the limit on that key's page in your settings, or, if you configured a daily, weekly, or monthly reset, until the spend window rolls over.

Managing key limits with the Management API

If you provision keys dynamically for separate background jobs, customers, or internal environments, you can manage keys programmatically through endpoints under /api/v1/keys.

These management routes reject standard API keys. You must pass a Management API key in the Authorization header.

Provisioning a Management API key

To set up programmatic management:

1. Go to the Management API Keys page at https://openrouter.ai/settings/management-keys.
2. Click "Create New Key".
3. Enter a name and choose an expiration.
4. Copy the key immediately when it appears. You won't be able to see it again.

Management API keys cannot make completion calls to models; they exist exclusively for administrative tasks. In an organization account, only Organization Admins can generate them. They are unscoped, meaning a single management key carries administrative authority across every workspace in your account.

A leaked management key can create, edit, and delete all API keys in your account except those provisioned by a Connect client. Keep its lifetime tight. The expiration date is locked at the moment of creation and cannot be changed later; extending access requires generating a brand new key and deleting the expired one. If a management key passes its expiration date, every administrative call fails with a 401 Unauthorized status and the message API key expired.

Creating and updating keys via API

To provision a new key with a spending cap, send a POST request to https://openrouter.ai/api/v1/keys. The JSON response returns the raw key string so you can save it securely:

curl -X POST https://openrouter.ai/api/v1/keys \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer Instance Key", "limit": 1000}'

To update an existing key, send a PATCH request to https://openrouter.ai/api/v1/keys/{keyHash}. You can update fields like name, disabled, include_byok_in_limit, and limit_reset:

curl -X PATCH https://openrouter.ai/api/v1/keys/$KEY_HASH \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit_reset": "daily"}'

You can list the most recent 100 API keys by calling GET /api/v1/keys, and paginate past that with the offset query parameter, such as ?offset=100. To fetch a specific key's metadata, call GET /api/v1/keys/{hash}. To remove a key permanently, send DELETE /api/v1/keys/{hash}.

Working within key-management rate limits

Creating, updating, and deleting keys with a management key counts toward a shared account and organization rate limit of 10,000 requests per day. This quota resets daily at 00:00 UTC.

Every write request counts against this 10,000-request quota, even if the call fails with a 404 error because of an unknown key hash. Reading keys, pulling usage, or checking account credits does not count toward this limit. If your architecture spins up short-lived keys for individual jobs, set expires_at when sending the initial POST /api/v1/keys request instead of calling DELETE when the job finishes. That single decision halves the number of administrative writes hitting your daily quota.

OpenRouter also enforces per-IP burst limits per minute across key writes, key reads, and balance checks, and these burst errors do not return X-RateLimit-* headers.

Budget check order and reset windows

OpenRouter doesn't check limits arbitrarily. On every paid request, enforcement follows a strict, sequential order before any provider processes the prompt:

1. Guardrail budgets: Checks limit_usd on the workspace default guardrail against member spend, then key spend, followed by individual member and key guardrails.
2. Workspace budgets: Enforces caps defined across the entire workspace's aggregate spend.
3. The key's own limit: Enforces the key's individual limit field once its window is spent.

All spending windows follow UTC time strictly. A daily budget resets at 00:00 UTC. A weekly budget resets on Monday at 00:00 UTC. A monthly budget rolls over on the first day of the calendar month at 00:00 UTC. A lifetime workspace budget never resets.

What happens when a key hits its limit: 403 vs 402 errors

When a request gets blocked, the HTTP status code tells you whether you hit a configured budget ceiling or ran out of account balance.

HTTP 403: Budget limits exhausted

If a key exhausts its credit limit, or hits a workspace or guardrail ceiling, OpenRouter blocks the call before it reaches the model provider and returns an HTTP 403 status.

The response payload contains error.metadata, which includes:

• limit_source: Set to openrouter_key_limit, openrouter_workspace_budget, or openrouter_guardrail_budget.
• scope: The exact enforcement level that blocked the call.
• limit_usd and spend_usd: The target cap and current spend.
• resets_at: The ISO 8601 UTC timestamp showing when the window rolls over, or null if the budget never resets.
• remedy_hint: Text explaining how to resolve the block.

Because the reset window is hours or days away, 403 responses do not include a Retry-After header. Retrying before the reset timestamp will fail identically.

HTTP 402: Account credits and in-flight budget caps

HTTP 402 errors indicate payment or account balance issues rather than a key's configured budget cap.

To prevent concurrent requests from outrunning your prepaid balance before settlement, OpenRouter calculates an estimated token cost up front for every paid call. This estimate covers input tokens plus the completion tokens allowed by max_tokens up to a fixed cap. Only token prices count toward this calculation; per-request fees, plugin charges, and image pricing are excluded. OpenRouter holds this estimated cost against an in-flight spending budget while the generation runs and during a brief settlement period afterward.

If your running requests fill this temporary allowance, you receive a 402 error where error.metadata.limit_source is openrouter_in_flight_budget and reason is in_flight_budget_exhausted. This error is transient; wait for the seconds indicated in the Retry-After response header and retry the request.

If a single prompt's estimated cost exceeds your whole available budget, you get a 402 error with limit_source set to openrouter_credits and reason set to weight_exceeds_budget. Lower your prompt size or max_tokens to fix it. Finally, if your overall balance drops below zero, OpenRouter returns 402 errors across all requests, including calls to free models, until you add fresh funds. For a breakdown of model costs and platform fees, see What does OpenRouter charge on top of model prices?.

Checking key usage and remaining credits

To inspect a key's active allowances without logging into the dashboard, query https://openrouter.ai/api/v1/key using the API key itself:

curl -fsS https://openrouter.ai/api/v1/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

The response returns the key's label, its limit, limit_remaining, and limit_reset status, alongside its usage counter for all-time spend. It also exposes usage_daily for the current UTC day, usage_weekly starting from Monday UTC, and usage_monthly.

{
  "data": {
    "limit": 100,
    "limit_remaining": 42.50,
    "limit_reset": "monthly",
    "include_byok_in_limit": false,
    "usage": 57.50,
    "usage_daily": 4.10,
    "usage_weekly": 18.20,
    "usage_monthly": 57.50
  }
}

The payload also includes effective_budget, indicating which budget will block requests first, and an array named budgets showing each applied guardrail and workspace limit with its remaining_usd and resets_at fields.

If you want to view overall account-level remaining credits instead of a single key's balance, make a GET /api/v1/credits request. This route strictly requires a Management API key and rejects regular completion keys.

Monitoring spend and setting brakes with Costbrake

Configuring credit limits directly on OpenRouter stops runaway keys, but it doesn't alert you when unexpected usage starts climbing across your other infrastructure.

Costbrake monitors spend across 23 cloud, AI, and SaaS platforms, including OpenRouter, AWS, OpenAI, Anthropic, and Vercel. Checks run hourly on the Free plan, every 5 minutes on Pro and Team, and accelerate to every minute during an active spike. It flags an alert whenever an hour costs more than 3x your 7-day baseline and at least $5 above normal, alongside threshold notifications at 50%, 80%, and 100% of your budgets.

For OpenRouter, Costbrake reads keys, credits, and usage activity. It also supports optional, human-confirmed brakes. If spend accelerates out of hand, an admin can click to disable a compromised key immediately, or drop its credit limit to $0 so paid calls halt while free models stay operational. You can connect keys manually or configure the integration by pointing your agent to agent setup. Review Costbrake pricing for details on team seats and notification channels.