POST
/
v1
/
ratelimits.limit
curl --request POST \
  --url https://api.unkey.dev/v1/ratelimits.limit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "namespace": "email.outbound",
  "identifier": "user_123",
  "limit": 10,
  "duration": 60000,
  "cost": 2,
  "async": false,
  "meta": {},
  "resources": [
    {
      "type": "project",
      "id": "p_123",
      "name": "dub"
    }
  ]
}'
{
  "success": true,
  "limit": 10,
  "remaining": 9,
  "reset": 1709804263654
}

​
Changelog

DateChanges
Mar 16 2024Introduced endpoint

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
identifier
string
required

Identifier of your user, this can be their userId, an email, an ip or anything else.

Example:

"user_123"

​
limit
integer
required

How many requests may pass in a given window.

Required range: x > 0
Example:

10

​
duration
integer
required

The window duration in milliseconds

Required range: x >= 1000
Example:

60000

​
namespace
string
default:
default

Namespaces group different limits together for better analytics. You might have a namespace for your public API and one for internal tRPC routes.

Example:

"email.outbound"

​
cost
integer
default:
1

Expensive requests may use up more tokens. You can specify a cost to the request here and we'll deduct this many tokens in the current window. If there are not enough tokens left, the request is denied.

Set it to 0 to receive the current limit without changing anything.

Required range: x >= 0
Example:

2

​
async
boolean
default:
false

Async will return a response immediately, lowering latency at the cost of accuracy.

​
meta
object

Attach any metadata to this request

​
resources
object[]

Resources that are about to be accessed by the user

Example:
[
  {
    "type": "project",
    "id": "p_123",
    "name": "dub"
  }
]

Response

200
application/json
​
success
boolean
required

Returns true if the request should be processed, false if it was rejected.

Example:

true

​
limit
integer
required

How many requests are allowed within a window.

Example:

10

​
remaining
integer
required

How many requests can still be made in the current window.

Example:

9

​
reset
integer
required

A unix millisecond timestamp when the limits reset.

Example:

1709804263654

Was this page helpful?

Suggest editsRaise issue
Delete an identitySet Override