docs(analytics): sync analytics skills with query builder

[jtcies]

Summary

Weekly sync of the analytics skills against the query builder in openrouter-web (packages/clickhouse/analytics/, services/cfw-public-api/src/routes/analytics/). Documents drift found this week plus older gaps still missing from the skills.

New this week:

• include_unset filter flag (openrouter-web #32182). Optional boolean, accepted only with in / not_in, and only for dimensions that declare an unset sentinel: api_key_id (-1), app (-1), user (empty string). Anything else fails validation with Dimension "<field>" has no unset bucket. The /meta response does not expose which dimensions have an unset bucket, so the skills now list them.
• Nil workspace UUID resolves to Unattributed in results (openrouter-web #31529).
• workspace filtering/grouping folds the legacy all-zero UUID into the account default workspace (openrouter-web #31855).

Pre-existing gaps also fixed:

• data_region dimension (global / europe / us, generations-only so 31-day limit) was undocumented.
• session_id was missing from the schema skill's 31-day dimension list.
• blended_cost_per_million_tokens metric was undocumented.
• Sentinel label buckets api_key_id = -1 -> Chatroom and app = -1 -> Unknown were undocumented.

Docs-only, no scripts changed.

Note for reviewers: several older open sync PRs propose overlapping subsets of this content (#100, #112, #151, #152, #156, #157). This PR covers all of them for the analytics skills, so those can be closed once this lands.

Link to Devin session: https://openrouter.devinenterprise.com/sessions/2eda26fe458a45ba973b1a2be0528c14
Requested by: @jtcies

---

[devin-ai-integration]

Original prompt from Joseph

# Weekly Analytics Skills Sync

You are responsible for keeping the analytics skills in OpenRouterTeam/skills in sync with the analytics query builder in OpenRouterTeam/openrouter-web. Post your findings to the Slack channel #proj-activity-observability (C0AKMN11K7G).

#``# Step 1: Check for recent query builder changes

Clone both repos:

• OpenRouterTeam/openrouter-web (query builder source of truth)
• OpenRouterTeam/skills (analytics skills that document the query builder)

Check git log for the last 7 days of changes in the query builder directory:

cd openrouter-web
git log --since="7 days ago" --oneline -- packages/clickhouse/analytics/

Also check the analytics route handlers:

git log --since="7 days ago" --oneline -- services/cfw-api/src/routes/analytics/

#``# Step 2: Read the current query builder state

Read these files to understand the current state of the query builder:

• packages/clickhouse/analytics/schemas.ts — MetricNameSchema, DimensionNameSchema, Granularity, FilterOperator definitions
• packages/clickhouse/analytics/metric-registry.ts — full metric definitions (name, displayLabel, availability, expressions, isRate, displayFormat)
• packages/clickhouse/analytics/dimension-registry.ts — full dimension definitions (name, displayLabel, mvColumn, generationsColumn, availableIn, clickhouseType)
• packages/clickhouse/analytics/operator-registry.ts — filter operator definitions
• packages/clickhouse/analytics/table-resolver.ts — table resolution logic
• packages/clickhouse/analytics/filter-builder.ts — filter building logic
• packages/clickhouse/analytics/enrichment/ — label resolution (which dimensions get labels)
• packages/clickhouse/analytics/trends/ — trends/leaderboard capabilities
• services/cfw-api/src/routes/analytics/get-meta.ts — what the meta endpoint exposes

#``# Step 3: Read the current analytics skills

Read these skill files:

• skills/openrouter-analytics/SKILL.md — main analytics skill
• ... (2986 chars truncated...)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[perry-the-pr-maintainer]

Perry's Review

Verdict: ✅ LGTM

Risk: 🟢 Low

Details

Summary

Docs-only PR syncing three analytics skill files (openrouter-analytics, openrouter-analytics-query, openrouter-analytics-schema) with the query builder implementation in openrouter-web. No scripts changed, no behavior changes — purely documentation of drift found this week plus older gaps.

What's documented

• include_unset filter flag (openrouter-web #32182) — optional boolean on in/not_in filters, valid only for dimensions with an unset bucket (api_key_id -1, app -1, user empty string). Consistently documented in both the query and schema skills.
• Sentinel label resolutions — api_key_id = -1 → Chatroom, app = -1 → Unknown, unresolved-workspace sentinel ffffffff-ffff-ffff-ffff-ffffffffffff → Unattributed. Added to all three skill files.
• Legacy all-zero UUID folding — workspace filtering/grouping by the account default workspace also covers activity recorded before workspace resolution existed. Documented consistently across all three files.
• data_region dimension — global/europe/us, generations-only (31-day limit). Added to schema skill's 31-day list, dimension categories, and query skill's timeout guidance.
• session_id 31-day limit — added to schema skill's time range limits list.
• blended_cost_per_million_tokens metric — total spend (incl. BYOK) per 1M tokens, NULL when no tokens. Added to schema skill's efficiency metrics and question-mapping table.

Consistency check

• Sentinel values (Chatroom, Unknown, Unattributed) are consistent across all three files.
• The include_unset semantics (in adds unset rows, not_in excludes them, empty array with in matches only unset) match between the query and schema skills.
• session_id's analytics representation (none) is correctly distinct from the raw generation metadata representation (null in openrouter-generations skill) — no contradiction.
• data_region is listed as 31-day in both the schema skill's time range limits and dimension categories, and added to the query skill's timeout guidance — consistent.

Risk assessment

Risk: 🟢 Low

Risk assessment:

Dimension	Severity	Risk	Reasoning
Implementation risk	🟩	Low	Docs-only change with no code, scripts, or behavior changes; content is internally consistent and accurately documents existing API behavior.
Premise risk	🟩	Low	The PR's premise (sync docs with the query builder) is straightforward and the documented features are clearly stated with specific sentinel values and error messages.
Estimated impact	🟩	Low	Worst case: a docs inaccuracy misleads an agent or developer using these skills — no runtime, data, or security impact.

Risk Factor	Severity	Risk	Reasoning
Reversibility	🟩	Low	Markdown docs — trivially reverted.
Detectability	🟩	Low	Any inaccuracy would surface when a developer or agent tries the documented feature and it doesn't match.
Blast radius	🟩	Low	Only the three analytics skill files; no code paths affected.
Data integrity		None	No persisted state is touched.
Financial exposure		None	No billing/payment code touched.
Security and privacy exposure		None	No secrets, auth, or tenant-isolation paths touched.
Propagation	🟩	Low	Downstream consumers of these skills (agents, developers) could be mildly misled, but no automated systems depend on the prose.
Availability		None	Docs-only; cannot affect serving.
Recovery cost	🟩	Low	A docs fix is a one-line edit.
Time to correct	🟩	Low	Spotted immediately on first use of a documented feature.