Query rate limit analytics

The POST /v2/analytics.getRatelimits endpoint runs SQL queries against your rate limit analytics. Use it from a trusted backend with a root key. Never expose a root key in browser code.

Send a query

Send a JSON object with a query string. The response uses the same shape as analytics.getVerifications: meta.requestId identifies the API request, and data contains an array of result objects.

curl --request POST \
  --url https://api.unkey.com/v2/analytics.getRatelimits \
  --header "Authorization: Bearer $UNKEY_ROOT_KEY" \
  --header "Content-Type: application/json" \
  --data '{"query":"SELECT identifier, passed, tokens FROM ratelimits_v1 WHERE namespace_id = '\''rlns_1234'\'' ORDER BY time DESC LIMIT 10"}'

{
  "meta": {
    "requestId": "req_1234"
  },
  "data": [
    {
      "identifier": "customer_123",
      "passed": true,
      "tokens": 1
    }
  ]
}

Queries follow the shared SQL and resource limits described in Query restrictions. CTEs, subqueries, UNION, and EXCEPT are supported. The query must contain a positive literal filter in one of these forms. You can optionally qualify namespace_id with a table alias:

WHERE namespace_id = 'rlns_1234'

WHERE r.namespace_id IN ('rlns_1234', 'rlns_5678')

You can name at most 10 unique namespace IDs. Every named namespace must exist and your root key must be authorized to access it. The root key needs ratelimit.<namespaceId>.read_analytics for each namespace, or the ratelimit.*.read_analytics wildcard permission.

Choose a table

Choose the least granular table that supports the chart or report. Aggregated tables scan fewer rows, while the raw table exposes individual requests and fields such as the applied limit, remaining tokens, and reset time.

Public table	Granularity	Retention	Best for
`ratelimits_v1`	Individual request	1 month	Recent request details and exact request times
`ratelimits_per_minute_v1`	Minute	7 days	Recent dashboard charts
`ratelimits_per_hour_v1`	Hour	30 days	Daily and weekly trends
`ratelimits_per_day_v1`	Day	100 days	Longer reports
`ratelimits_per_month_v1`	Month	3 years	Long-term trends

Your workspace retention setting controls the time range that a query can request. If you omit a time filter, Unkey automatically constrains results to your workspace retention range. A query that stays within your workspace quota can request a range beyond a table’s retention, but it returns only the rows that remain in that table. For example, a 30-day query against the minute table can contain partial data because that table retains 7 days. Select the hour table when you need the complete 30-day range.

Reference available columns

The raw table contains one row for each rate limit request.

Column	Description
`request_id`	Unique request ID
`time`	Request time as a Unix timestamp in milliseconds
`namespace_id`	Rate limit namespace ID
`identifier`	Identifier that was limited
`passed`	Whether the request passed the rate limit
`override_id`	Applied override ID, when an override matched
`limit`	Applied token limit
`remaining`	Tokens remaining after the request
`reset_at`	Reset time as a Unix timestamp in milliseconds
`tokens`	Tokens requested

The minute, hour, day, and month tables contain pre-aggregated rows.

Column	Description
`time`	Start of the aggregation interval
`namespace_id`	Rate limit namespace ID
`identifier`	Identifier that was limited
`passed`	Number of requests that passed the rate limit
`total`	Number of requests
`total_tokens`	Number of requested tokens
`passed_tokens`	Number of tokens from passed requests

Build a zero-filled time series

Use WITH FILL to return every minute, including intervals without requests. This query produces passed, blocked, and total metrics for both requests and tokens, which supports a dashboard chart without client-side gap filling.

SELECT
  time,
  sum(passed) AS passed_requests,
  sum(total) - sum(passed) AS blocked_requests,
  sum(total) AS total_requests,
  sum(passed_tokens) AS passed_tokens,
  sum(total_tokens) - sum(passed_tokens) AS blocked_tokens,
  sum(total_tokens) AS total_tokens
FROM ratelimits_per_minute_v1
WHERE namespace_id = 'rlns_1234'
  AND time >= toStartOfMinute(now() - INTERVAL 6 HOUR)
  AND time < toStartOfMinute(now())
GROUP BY time
ORDER BY time WITH FILL
  FROM toStartOfMinute(now() - INTERVAL 6 HOUR)
  TO toStartOfMinute(now())
  STEP INTERVAL 1 MINUTE

curl --request POST \
  --url https://api.unkey.com/v2/analytics.getRatelimits \
  --header "Authorization: Bearer $UNKEY_ROOT_KEY" \
  --header "Content-Type: application/json" \
  --data '{"query":"SELECT time, sum(passed) AS passed_requests, sum(total) - sum(passed) AS blocked_requests, sum(total) AS total_requests, sum(passed_tokens) AS passed_tokens, sum(total_tokens) - sum(passed_tokens) AS blocked_tokens, sum(total_tokens) AS total_tokens FROM ratelimits_per_minute_v1 WHERE namespace_id = '\''rlns_1234'\'' AND time >= toStartOfMinute(now() - INTERVAL 6 HOUR) AND time < toStartOfMinute(now()) GROUP BY time ORDER BY time WITH FILL FROM toStartOfMinute(now() - INTERVAL 6 HOUR) TO toStartOfMinute(now()) STEP INTERVAL 1 MINUTE"}'

Combine multiple identifiers

Filter with IN and omit identifier from GROUP BY to combine several identifiers into one result. This example returns daily totals for three customers.

SELECT
  time,
  sum(passed) AS passed_requests,
  sum(total) - sum(passed) AS blocked_requests,
  sum(total) AS total_requests,
  sum(passed_tokens) AS passed_tokens,
  sum(total_tokens) - sum(passed_tokens) AS blocked_tokens,
  sum(total_tokens) AS total_tokens
FROM ratelimits_per_day_v1
WHERE namespace_id = 'rlns_1234'
  AND identifier IN ('customer_123', 'customer_456', 'customer_789')
  AND time >= toStartOfDay(now() - INTERVAL 30 DAY)
GROUP BY time
ORDER BY time ASC

curl --request POST \
  --url https://api.unkey.com/v2/analytics.getRatelimits \
  --header "Authorization: Bearer $UNKEY_ROOT_KEY" \
  --header "Content-Type: application/json" \
  --data '{"query":"SELECT time, sum(passed) AS passed_requests, sum(total) - sum(passed) AS blocked_requests, sum(total) AS total_requests, sum(passed_tokens) AS passed_tokens, sum(total_tokens) - sum(passed_tokens) AS blocked_tokens, sum(total_tokens) AS total_tokens FROM ratelimits_per_day_v1 WHERE namespace_id = '\''rlns_1234'\'' AND identifier IN ('\''customer_123'\'', '\''customer_456'\'', '\''customer_789'\'') AND time >= toStartOfDay(now() - INTERVAL 30 DAY) GROUP BY time ORDER BY time ASC"}'

Paginate an identifier breakdown

Group by identifier to build a table with usage totals and the last request time. The secondary identifier sort makes ordering stable when multiple rows have the same request count. Keep the same ordering while changing OFFSET for subsequent pages.

SELECT
  identifier,
  max(time) AS last_request_time,
  countIf(passed) AS passed_requests,
  countIf(not passed) AS blocked_requests,
  count() AS total_requests,
  sumIf(tokens, passed) AS passed_tokens,
  sumIf(tokens, not passed) AS blocked_tokens,
  sum(tokens) AS total_tokens
FROM ratelimits_v1
WHERE namespace_id = 'rlns_1234'
  AND time >= toUnixTimestamp64Milli(now64(3) - INTERVAL 7 DAY)
GROUP BY identifier
ORDER BY total_requests DESC, identifier ASC
LIMIT 50 OFFSET 0

curl --request POST \
  --url https://api.unkey.com/v2/analytics.getRatelimits \
  --header "Authorization: Bearer $UNKEY_ROOT_KEY" \
  --header "Content-Type: application/json" \
  --data '{"query":"SELECT identifier, max(time) AS last_request_time, countIf(passed) AS passed_requests, countIf(not passed) AS blocked_requests, count() AS total_requests, sumIf(tokens, passed) AS passed_tokens, sumIf(tokens, not passed) AS blocked_tokens, sum(tokens) AS total_tokens FROM ratelimits_v1 WHERE namespace_id = '\''rlns_1234'\'' AND time >= toUnixTimestamp64Milli(now64(3) - INTERVAL 7 DAY) GROUP BY identifier ORDER BY total_requests DESC, identifier ASC LIMIT 50 OFFSET 0"}'

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

Query rate limit analytics

Send a query

Choose a table

Reference available columns

Build a zero-filled time series

Combine multiple identifiers

Paginate an identifier breakdown

​Send a query

​Choose a table

​Reference available columns

​Build a zero-filled time series

​Combine multiple identifiers

​Paginate an identifier breakdown

Send a query

Choose a table

Reference available columns

Build a zero-filled time series

Combine multiple identifiers

Paginate an identifier breakdown