get-verifications

Execute custom SQL queries against your key verification analytics. Use this to inspect verification patterns, monitor outcomes, and build custom reports over your key usage data. Only SELECT queries are allowed. The response rows are dynamic — fields vary based on your SQL SELECT clause and can include any combination of columns such as time, outcome, count, key_id, and more. For complete documentation including available tables, columns, data types, and query examples, see the schema reference in the API documentation. Required permissions:

analytics.*.read_verifications (to query verification analytics)

See the API reference for the full HTTP endpoint documentation.

Usage

unkey api analytics get-verifications [flags]

Flags

string

required

SQL SELECT query to execute against your analytics data. Only SELECT queries are allowed. The query runs against the key_verifications_v1 table, which contains columns like time, key_id, outcome, and more. See the API reference for the full schema.

Global Flags

Flag	Type	Description
`--root-key`	string	Override root key (`$UNKEY_ROOT_KEY`)
`--api-url`	string	Override API base URL (default: `https://api.unkey.com`)
`--config`	string	Path to config file (default: `~/.unkey/config.toml`)
`--output`	string	Output format. Use `json` for raw JSON
`--body`	string	Send this JSON string as the request body. You cannot combine it with request-building flags.

Examples

unkey api analytics get-verifications --query="SELECT COUNT(*) as total FROM key_verifications_v1 WHERE outcome = 'VALID' AND time >= now() - INTERVAL 7 DAY"

unkey api analytics get-verifications --query="SELECT key_id, outcome, COUNT(*) as cnt FROM key_verifications_v1 GROUP BY key_id, outcome"

unkey api analytics get-verifications --query="SELECT outcome, COUNT(*) as total FROM key_verifications_v1 GROUP BY outcome" --output=json

Output

Default output shows the request ID, followed by the query results:

req_2c9a0jf23l4k567

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

With --output=json, the full response envelope is returned:

{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": [
    {
      "outcome": "VALID",
      "count": 1234,
      "time": 1696118400000
    },
    {
      "outcome": "RATE_LIMITED",
      "count": 56,
      "time": 1696118400000
    }
  ]
}

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

Usage

Flags

Global Flags

Examples

Output

​Usage

​Flags

​Global Flags

​Examples

​Output

Usage

Flags

Global Flags

Examples

Output