Query Analytics

​

Overview

​

POST /v2/analytics.getVerifications

​

Request

SELECT COUNT(*) as total 
FROM key_verifications_v1 
WHERE outcome = 'VALID' 
  AND time >= now() - INTERVAL 7 DAY

​

Response

[
  {
    "outcome": "VALID",
    "count": 1234,
    "time": 1696118400000
  },
  {
    "outcome": "RATE_LIMITED",
    "count": 56,
    "time": 1696118400000
  }
]

​

Example

curl -X POST https://api.unkey.com/v2/analytics.getVerifications \
  -H "Authorization: Bearer <your-root-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT COUNT(*) as total FROM key_verifications_v1 WHERE outcome = '"'"'VALID'"'"' AND time >= now() - INTERVAL 7 DAY"
  }'

{
  "meta": {
    "requestId": "req_01H9TQPP77V5E48E9SH0BG0ZQX"
  },
  "data": [
    {
      "total": 45678
    }
  ]
}

​

Common Query Examples

SELECT outcome, COUNT(*) as count
FROM key_verifications_v1
WHERE time >= now() - INTERVAL 24 HOUR
GROUP BY outcome

SELECT key_id, COUNT(*) as verifications
FROM key_verifications_v1
WHERE time >= now() - INTERVAL 7 DAY
GROUP BY key_id
ORDER BY verifications DESC
LIMIT 10

SELECCT 
  toStartOfHour(time) as hour,
  COUNT(*) as total_verifications
FROM key_verifications_v1
WHERE time >= now() - INTERVAL 24 HOUR
GROUP BY hour
ORDER BY hour

​

Error Codes

• 400 - Bad request (invalid SQL query or blocked operation)
• 401 - Unauthorized (missing or invalid authentication)
• 403 - Forbidden (insufficient permissions)
• 404 - Not found (referenced API or identity not found)
• 422 - Unprocessable entity (query exceeds resource limits: timeout, memory, rows scanned, or result size)
• 429 - Too many requests (query quota exceeded)
• 500 - Internal server error (query execution failed)
• 503 - Service unavailable (connection to the database failed)

​

Query Limits

• Execution timeout: Queries must complete within a reasonable time frame
• Memory usage: Limited memory available per query
• Rows scanned: Maximum number of rows that can be scanned
• Result size: Maximum size of the result set

• Narrowing the time range
• Adding more specific WHERE clauses
• Reducing the number of columns selected
• Using aggregation to reduce result size