Analytics

Track usage per key, per API, and with custom tags

Unkey provides analytics at multiple levels — see overall API usage, drill down into individual keys, and use tags to segment data however you need.

What you can track

API-level metrics

Total verifications, active keys, usage trends across your entire API.

Key-level metrics

Per-key usage, success/failure rates, geographic distribution.

Custom tags

Add context to verifications: endpoint, resource, version, region.

Identity tracking

Track usage across multiple keys for the same user.

Per-API analytics

The dashboard shows aggregate metrics for each API:

• Total keys: How many keys exist for this API
• Active keys: Keys used in the last 30 days
• Verifications: Total verification requests over time
• Success/failure rates: Valid vs invalid/expired/rate-limited

Per-key analytics

Drill into individual keys to see:

• Usage over time: Verification volume by day/hour
• Geographic distribution: Where requests originate
• Response codes: Success, rate limited, expired, etc.
• Remaining credits: If using usage limits

Tags: Custom dimensions

Tags let you add context to verification requests. Later, you can filter and aggregate analytics by these tags.

Example use cases

• By endpoint: path=/v1/posts.create — see which endpoints are most used
• By resource: postId=post_123 — track access to specific resources
• By version: apiVersion=2.1.0 — compare usage across versions
• By region: region=us-east-1 — geographic breakdown

Adding tags to verification

Include up to 10 tags per verification request:

cURL

curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -d '{
    "key": "sk_...",
    "tags": [
      "path=/v1/posts.create",
      "postId=post_abc123",
      "region=us-east-1"
    ]
  }'

Tag format

Tags are arbitrary strings. Unkey doesn’t parse them, but we recommend key-value format for consistency:

key=value
key:value

Limits:

• Up to 10 tags per request
• Each tag: 1-128 characters

Tag naming conventions

Pick a convention and stick with it:

// Good: consistent key=value format
const tags = [
  "endpoint=/v1/users",
  "method=POST",
  "version=2024-01",
];

// Also good: namespaced
const tags = [
  "api.endpoint=/v1/users",
  "api.method=POST",
  "deploy.sha=abc123",
];

Identity-level analytics

When keys are linked to an identity, you can track usage across all keys belonging to that identity. This is useful when users have multiple keys (e.g., different environments or applications).

try {
  const { meta, data } = await unkey.keys.create({
    apiId: "api_...",
    identity: {
      externalId: "user_123",  // Links to this user
    },
  });
  console.log(data.keyId);
} catch (err) {
  console.error(err);
  return Response.json({ error: "Internal error" }, { status: 500 });
}

Now analytics can be viewed per-user, aggregating all their keys.

Querying analytics

Analytics can be queried via the API for building custom dashboards:

// Get verification stats for a key
try {
  const { meta, data } = await unkey.analytics.getKeyStats({
    keyId: "key_...",
    start: Date.now() - 30 * 24 * 60 * 60 * 1000, // Last 30 days
    end: Date.now(),
  });
  console.log(data);
} catch (err) {
  console.error(err);
  return Response.json({ error: "Internal error" }, { status: 500 });
}

We’re working on a v2 analytics API with advanced SQL querying capabilities. Contact us if you’re interested in early access.

Common patterns

Finding your top users

Query keys sorted by verification count to identify power users or potential abuse.

Tracking feature adoption

Tag verifications with feature names to see which features are most used:

const tags = data.meta?.features ?? [];
// tags: ["feature=export", "feature=bulk-upload"]

Billing and usage reports

Combine verification counts with custom costs to generate accurate usage reports for billing.

Next steps

Usage limits

Cap total requests and track remaining credits

Identities

Group keys by user for aggregate analytics