Getting Started - Unkey Docs

Request Access#

Warning

Analytics is currently in private beta and available by request only.

To get started:

Find your workspace ID in the Unkey dashboard settings
Email us at support@unkey.com with:
- Your workspace ID
- Your use case (billing, dashboards, reporting, etc.)
- Expected query volume

We'll enable analytics for your workspace and send you confirmation.

Authentication#

Analytics queries require a root key with analytics permissions. Create one in your dashboard:

Go to Settings → Root Keys
Click Create New Root Key
Select permissions: api.*.read_analytics OR api.<api_id>.read_analytics
Copy and securely store your root key

Warning

Root keys have powerful permissions. Store them securely and never commit them to version control.

Your First Query#

Once you have access, execute your first analytics query using the /v2/analytics.getVerifications endpoint.

Count Total Verifications#

Count the total number of key verifications in the last 7 days across all your keyspaces to get a high-level view of your overall usage volume.

SELECT SUM(count) as totalFROM key_verifications_per_day_v1WHERE time >= now() - INTERVAL 7 DAY

Break Down by Outcome#

Group verifications by their outcome (VALID, RATE_LIMITED, USAGE_EXCEEDED, etc.) over the last 24 hours to understand the distribution of successful vs. failed requests.

SELECT  outcome,  SUM(count) as countFROM key_verifications_per_hour_v1WHERE time >= now() - INTERVAL 24 HOURGROUP BY outcomeORDER BY count DESC

Top Users by Usage#

Identify your most active users by counting their total verifications over the last 30 days to spot power users or potential abuse patterns.

SELECT  external_id,  SUM(count) as verificationsFROM key_verifications_per_day_v1WHERE time >= now() - INTERVAL 30 DAYGROUP BY external_idORDER BY verifications DESCLIMIT 10

Tip

Performance tip: For longer time ranges, use pre-aggregated tables instead of the raw table:

key_verifications_per_minute_v1 - For queries spanning hours
key_verifications_per_hour_v1 - For queries spanning days
key_verifications_per_day_v1 - For queries spanning weeks/months
key_verifications_per_month_v1 - For queries spanning years

Use SUM(count) instead of COUNT(*) with aggregated tables. They scan far fewer rows and are much faster.

Tip

Check out the Query Examples page for 30+ ready-to-use queries covering billing, monitoring, and analytics use cases.

Understanding the Response#

Analytics queries return data as an array of objects:

{  "meta": {    "requestId": "req_xxx"  },  "data": [    { "outcome": "VALID", "count": 1234 },    { "outcome": "RATE_LIMITED", "count": 56 },    { "outcome": "USAGE_EXCEEDED", "count": 12 }  ]}

Each object in the data array contains fields from your SELECT clause. The field names match the column names or aliases you specified in your query.

Filtering by keyspace or user#

You can filter queries to specific keyspaces or users. Use key_space_id to filter by keyspace (find this identifier in your Keyspace Settings) and external_id to filter by user. These fields support standard SQL operators: =, !=, IN, NOT IN, <, >, etc.

Note

Automatic filtering: All queries are automatically filtered based on your root key's permissions:

Workspace filtering: All queries are scoped to your workspace. You do not need to filter by workspace_id.
Keyspace filtering: If your root key has api.<api_id>.read_analytics permissions (scoped to a specific keyspace), queries are automatically filtered to that keyspace's key_space_id. If your root key has api.*.read_analytics (all keyspaces), you should filter by key_space_id yourself to query specific keyspaces.

Note

Queries are subject to resource limits (execution time, memory, result size, and quota). See Query Restrictions for complete details on limits and error codes.