Skip to content

docs: Python and Go examples #5058

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
perkinsjr wants to merge 25 commits into
base: main
Choose a base branch
from
Draft

docs: Python and Go examples #5058

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
ece9221
Add Python and Go SDK documentation
perkinsjr Feb 15, 2026
4a5bfcb
Add final Python cookbook recipe and 5-minutes guide
perkinsjr Feb 16, 2026
a41d3d0
Update docs.json sidebar navigation
perkinsjr Feb 16, 2026
7885556
Add Go examples to quickstart and reorganize cookbook by language
perkinsjr Feb 16, 2026
534fe6d
Update cookbook index with new Go and Python recipes
perkinsjr Feb 16, 2026
5e0897b
Fix code issues in Go and Python documentation
perkinsjr Feb 16, 2026
c4643aa
Fix async/sync issue and nil pointer in quickstart docs
perkinsjr Feb 16, 2026
1168f1f
Fix more code issues in documentation
perkinsjr Feb 16, 2026
8f51c90
Fix missing os import in python-flask-auth.mdx
perkinsjr Feb 16, 2026
ec70a7f
Fix unsafe type assertions in Go middleware docs
perkinsjr Feb 16, 2026
22e5d1d
Fix error handling in Python docs - replace ApiError with UnkeyError
perkinsjr Feb 16, 2026
a3092d6
Update legacy analytics documentation
perkinsjr Feb 16, 2026
c023b1f
fix
perkinsjr Feb 16, 2026
14c22ba
Update to mint
perkinsjr Feb 16, 2026
2fe40cd
Fix critical type assertion issues in go-gin-middleware
perkinsjr Feb 17, 2026
ea3ff1a
Merge branch 'main' into docs-python-go-sdks
perkinsjr Feb 17, 2026
d2a03e2
Merge branch 'docs-python-go-sdks' of github.com:unkeyed/unkey into d…
perkinsjr Feb 17, 2026
331f32f
Add it back
perkinsjr Feb 17, 2026
8cc910e
Merge branch 'main' into docs-python-go-sdks
perkinsjr Feb 17, 2026
42e05ad
fix the comma
perkinsjr Feb 17, 2026
7567ec4
Merge branch 'docs-python-go-sdks' of github.com:unkeyed/unkey into d…
perkinsjr Feb 17, 2026
fd61971
revert
perkinsjr Feb 17, 2026
f19ff76
Update go examples
perkinsjr Feb 17, 2026
2e40a64
cookbook update
perkinsjr Feb 17, 2026
9f0854d
update quickstart
perkinsjr Feb 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
223 changes: 36 additions & 187 deletions web/apps/docs/apis/features/analytics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,209 +1,58 @@
---
title: Analytics
description: 'Track usage per key, per API, and with custom tags'
description: 'Query your verification data with SQL'
---

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

## What you can track
Unkey Analytics provides a powerful SQL interface to query your API key verification data. Instead of building your own analytics pipeline, you can leverage Unkey's built-in data warehouse to:

<CardGroup cols={2}>
<Card title="API-level metrics" icon="chart-line">
Total verifications, active keys, usage trends across your entire API.
</Card>
<Card title="Key-level metrics" icon="key">
Per-key usage, success/failure rates, geographic distribution.
</Card>
<Card title="Custom tags" icon="tags">
Add context to verifications: endpoint, resource, version, region.
</Card>
<Card title="Identity tracking" icon="user">
Track usage across multiple keys for the same user.
</Card>
</CardGroup>
- **Build custom dashboards** for internal teams or end-users
- **Power usage-based billing** by querying verification counts per user/organization
- **Generate reports** on API usage patterns, top users, and performance metrics
- **Monitor and alert** on verification outcomes, rate limits, and errors

## Per-API analytics
<Card title="Get Started with Analytics" icon="chart-line" href="/analytics/overview">
Learn how to query your verification data using SQL
</Card>

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

<Frame caption="Per API Analytics">
<img src="/images/per-api-analytics.png" alt="Per API Analytics"/>
</Frame>

## 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
## What's Available

<Frame caption="Per Key Analytics">
<img src="/images/per-key-analytics.png" alt="Per key analytics"/>
</Frame>
The new Analytics platform includes:

## 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:

<CodeGroup>

```bash 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"
]
}'
```

```typescript TypeScript
try {
const { meta, data } = await verifyKey({
key: "sk_...",
apiId: "api_...",
tags: [
"path=/v1/posts.create",
"postId=post_abc123",
"region=us-east-1",
],
});

if (!data.valid) {
return Response.json({ error: data.code }, { status: 401 });
}
} catch (err) {
console.error(err);
return Response.json({ error: "Internal error" }, { status: 500 });
}
```

</CodeGroup>

### 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:

```typescript
// 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](/concepts/identities/overview), 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).

```typescript
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:

```typescript
// 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 });
}
```
- **SQL querying** of verification data
- **Time-series aggregations** (minute, hour, day, month tables)
- **Automatic filtering** by workspace and API
- **Custom dashboards** and reporting

<Note>
We're working on a v2 analytics API with advanced SQL querying capabilities. Contact us if you're interested in early access.
Analytics is currently in private beta. See [Getting Started](/analytics/getting-started) for access instructions.
</Note>

## Common patterns

### Finding your top users
## Dashboard Analytics

Query keys sorted by verification count to identify power users or potential abuse.
### Per API Metrics

### Tracking feature adoption
The dashboard shows aggregate metrics for each API:

Tag verifications with feature names to see which features are most used:
- **Total Verifications**: Total number of API key verifications
- **Success Rate**: Percentage of successful verifications
- **Rate Limit Exceeded**: Number of rate limit exceeded errors
- **Invalid Key**: Number of invalid key errors

```typescript
const tags = data.meta?.features ?? [];
// tags: ["feature=export", "feature=bulk-upload"]
```
<Frame caption="Per API Analytics">
<img src="/images/per-api-analytics.png" alt="Per API Analytics"/>
</Frame>

### Billing and usage reports
### Per Key Metrics

Combine verification counts with custom costs to generate accurate usage reports for billing.
The dashboard shows aggregate metrics for each API key:

## Next steps
- **Total Verifications**: Total number of API key verifications
- **Success Rate**: Percentage of successful verifications
- **Rate Limit Exceeded**: Number of rate limit exceeded errors
- **Invalid Key**: Number of invalid key errors

Comment on lines +32 to 55
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Per‑API and Per‑Key metric sections are identical.

Both lists repeat the same bullets; readers will expect distinct per‑API vs per‑key details. Consider merging into one shared list or adding differentiating metrics for each section.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@web/apps/docs/apis/features/analytics.mdx` around lines 32 - 55, The "Per API
Metrics" and "Per Key Metrics" sections currently list identical bullets, which
is confusing; update the "Per API Metrics" and/or "Per Key Metrics" sections
under the headings "Per API Metrics" and "Per Key Metrics" so they either (a)
merge into a single shared "Metrics" list (removing the duplicate section) or
(b) provide distinct metrics for each scope (e.g., per-API: "Active API
endpoints", "Average latency per endpoint", "Error rate by endpoint"; per-key:
"Usage per key", "Monthly quota", "Last seen timestamp"), and ensure the <Frame
caption="Per API Analytics"> example image and captions reflect the chosen
change.

<CardGroup cols={2}>
<Card title="Usage limits" icon="calculator" href="/apis/features/remaining">
Cap total requests and track remaining credits
</Card>
<Card title="Identities" icon="user" href="/concepts/identities/overview">
Group keys by user for aggregate analytics
</Card>
</CardGroup>
<Frame caption="Per Key Analytics">
<img src="/images/per-key-analytics.png" alt="Per Key Analytics"/>
</Frame>
Loading