Skip to content

docs(openrouter-analytics-query): sync with openrouter-web changes #156

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

Open
devin-ai-integration wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(openrouter-analytics-query): sync with openrouter-web changes #156

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
04e4418
docs(analytics): document unset filter buckets
devin-ai-integration[bot] Aug 5, 2026
0330abd
docs(openrouter-analytics-query): document possible-cache rollup cons…
devin-ai-integration[bot] Aug 17, 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
12 changes: 10 additions & 2 deletions skills/openrouter-analytics-query/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,11 +82,17 @@ cd <openrouter-analytics-skill-path>/scripts && npx tsx query-analytics.ts --met
### Filter Object Shape

```json
{ "field": "<dimension_name>", "operator": "<op>", "value": "<value>" }
{
"field": "<dimension_name>",
"operator": "<op>",
"value": "<value>",
"include_unset": true
}
```

- Scalar operators (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`): `value` is a string or number
- Array operators (`in`, `not_in`): `value` is an array of strings or numbers
- `include_unset: true` includes rows where the dimension has no value. It is supported only with `in` and `not_in`, and only for dimensions that have an unset bucket.
- Several dimensions are **label-resolved** in query results (returned as human-readable names), but filters must use the underlying ID:
- `api_key_id` — numeric ID (from generation metadata) or 64-char SHA-256 hash (from `GET /api/v1/keys`). Hashes are auto-resolved to numeric IDs before querying.
- `user` — Clerk user ID (e.g. `user_abc123`), not the display name/email shown in results.
Expand Down Expand Up @@ -321,7 +327,7 @@ Combine up to 2 dimensions for cross-tabulation:

| Status | Meaning | Action |
|---|---|---|
| 400 | Invalid query (bad metric name, too many dimensions, invalid time range) | Check the meta endpoint for valid values. Verify time range start < end. Max 2 dimensions, 20 filters. |
| 400 | Invalid query (bad metric name, too many dimensions, invalid time range, incompatible possible-cache combination) | Check the meta endpoint for valid values. Verify time range start < end. Max 2 dimensions, 20 filters. The error body names the incompatible field when possible-cache metrics are involved. |
| 401 | Invalid or missing API key | Check `OPENROUTER_API_KEY` is set correctly |
| 403 | Not a management key | The key must be a provisioning/management key. Create one at openrouter.ai/settings/management-keys |
| 408 | Query timed out | Narrow the time range, reduce dimensions, or add filters to scan less data |
Expand All @@ -336,6 +342,8 @@ Usage breakdown metrics follow the same pattern: `credits_usage`, `usage_upstrea

Classifier dimensions and classifier filters always force the 31-day time range limit.

The possible-cache metrics (`possible_cached_tokens`, `possible_cache_hit_rate`, `cache_capture_rate`) always read the hourly possible-cache rollup, so they are capped at **31 days** regardless of granularity, and can only be combined with `tokens_prompt`, `cached_tokens`, `cache_hit_rate`, `model`/`provider` grouping and filters, and `hour` granularity or coarser. Anything else — another metric, another dimension or filter field, `minute` granularity, classifier dimensions or filters — returns 400 naming the incompatible parts instead of falling back to another source.

If a query times out, try:
- Narrowing the time range
- Removing latency/throughput metrics
Expand Down