Skip to main content

Documentation Index

Fetch the complete documentation index at: https://unkey.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Usage limits let you set a maximum number of requests a key can make. After the limit is reached, the key becomes invalid until you add more credits or reset it. This is different from rate limiting, which controls frequency, usage limits control total volume.

​
When to use this

Pay-per-use APIs

Sell API credits that get consumed with each request. Customer buys 10,000 requests, key stops working at 10,001.

Trial/freemium tiers

Give new users 100 free requests to try your API. They upgrade or stop.

Subscription quotas

“Pro plan includes 50,000 requests/month”, combine with auto-refill for recurring limits.

One-time tokens

Create a key that works exactly once, like a single-use download link.

​
How it works

  1. Create a key with credits.remaining set to your limit
  2. Each verification decrements the remaining count
  3. When remaining hits 0, verification fails with code: USAGE_EXCEEDED
  4. You can add more credits anytime via the API

​
Create a key with usage limits

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "credits": {
      "remaining": 1000
    }
  }'

​
Verification response

When you verify a key with usage limits, the response includes the current credit count: 
{
  "meta": { "requestId": "req_..." },
  "data": {
    "valid": true,
    "code": "VALID",
    "keyId": "key_...",
    "credits": 999
  }
}
The credits value shows remaining credits after this verification. A value of 999 means the key can be verified 999 more times.
When credits are exhausted: 
{
  "meta": { "requestId": "req_..." },
  "data": {
    "valid": false,
    "code": "USAGE_EXCEEDED",
    "keyId": "key_...",
    "credits": 0
  }
}

​
Custom cost per request

By default, each verification costs 1 credit. But some operations should cost more, maybe a complex query costs 10 credits while a simple lookup costs 1. Specify the cost at verification time: 
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -d '{
    "key": "sk_...",
    "credits": {
      "cost": 10
    }
  }'
If the key doesn’t have enough remaining credits, the verification fails. A key with 5 remaining credits will reject a request with cost: 10.

​
Cost of 0 (check without consuming)

Set cost: 0 to verify a key without consuming any credits. Useful for checking key validity or metadata without affecting the balance. 
{
  "key": "sk_...",
  "credits": { "cost": 0 }
}

​
Add more credits

When a user purchases more credits or you need to refill manually: 
curl -X POST https://api.unkey.com/v2/keys.updateCredits \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_...",
    "operation": "increment",
    "value": 5000
  }'
Operations available:
  • set, Set credits to an exact value
  • increment, Add credits to current balance
  • decrement, Subtract credits from current balance

​
Remove usage limits

To make a key unlimited again, set credits to null: 
curl -X POST https://api.unkey.com/v2/keys.updateKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_...",
    "credits": null
  }'

​
Usage limits vs rate limits

FeatureUsage LimitsRate Limits
What it controlsTotal requests everRequests per time window
Resets automatically?No (unless using refill)Yes, after window expires
Use caseBilling, quotas, trialsAbuse protection, fair usage
Example”1000 requests total""100 requests per minute”
Use both together: Rate limits protect against burst abuse, usage limits enforce billing quotas.

​
Next steps

Auto-refill

Automatically reset credits on a schedule (daily, monthly)

Rate limiting

Control request frequency, not just total volume
Last modified on May 6, 2026