Usage Limits (Credits)

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#

Create a key with credits.remaining set to your limit
Each verification decrements the remaining count
When remaining hits 0, verification fails with code: USAGE_EXCEEDED
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  }}

Note

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    }  }'

Warning

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#

Feature	Usage Limits	Rate Limits
What it controls	Total requests ever	Requests per time window
Resets automatically?	No (unless using refill)	Yes, after window expires
Use case	Billing, quotas, trials	Abuse 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