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": true,
  "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
headerrequired

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

Body

application/json
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.

identifier
string
required

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

limit
integer
required

How many requests may pass in a given window.

duration
integer
required

The window duration in milliseconds

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.

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

Response

200 - application/json
success
boolean
required

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

limit
integer
required

How many requests are allowed within a window.

remaining
integer
required

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

reset
integer
required

A unix millisecond timestamp when the limits reset.

Was this page helpful?

Delete an APIMigrate key to Unkey