/openrouter-analytics-query

name: openrouter-analytics-query
description: Construct and execute analytics queries against the OpenRouter API — full parameter reference for metrics, dimensions, filters, time ranges, ordering, and pagination. Use when building or debugging an analytics query, understanding the request/response shape, or handling query errors.
version: 0.1.0

OpenRouter Analytics Query Execution

Full reference for constructing and executing analytics queries against the OpenRouter API.

Prerequisites

• `OPENROUTER_API_KEY` must be set to a **management key**. Management keys are separate from regular API keys — get one at https://openrouter.ai/settings/management-keys

Query Endpoint

POST https://openrouter.ai/api/v1/analytics/query
Authorization: Bearer sk-or-v1-...
Content-Type: application/json

Or via the `openrouter-analytics` skill scripts:

cd <openrouter-analytics-skill-path>/scripts && npx tsx query-analytics.ts --metrics request_count

> **Source of truth (avoid drift):** the metric/dimension names and the request schema below are illustrative. The live, authoritative list comes from the **meta endpoint** — call `GET /api/v1/analytics/meta` (or `discover-schema.ts`) and treat its response as canonical. For agent-readable docs, OpenRouter publishes [`llms.txt`](https://openrouter.ai/docs/llms.txt). Prefer those over the inline examples in this file if they ever disagree.

Request Schema

{
  "metrics": ["request_count", "total_usage"],
  "dimensions": ["model"],
  "granularity": "day",
  "time_range": {
    "start": "2026-05-01T00:00:00Z",
    "end": "2026-05-20T00:00:00Z"
  },
  "filters": [
    { "field": "model", "operator": "eq", "value": "anthropic/claude-sonnet-4" }
  ],
  "order_by": { "field": "total_usage", "direction": "desc" },
  "limit": 100,
  "group_limit": 20,
  "classifier_dimensions": {
    "classifier_id": "<uuid>",
    "dimension_names": ["category"],
    "include_nulls": false
  },
  "classifier_filters": {
    "classifier_id": "<uuid>",
    "filters": [
      { "field": "sentiment", "operator": "eq", "value": "positive" }
    ]
  }
}

Required Fields

| Field | Type | Description | |---|---|---| | `metrics` | `string[]` | At least one metric to compute. Call the meta endpoint to see available metrics. |

Optional Fields

| Field | Type | Default | Description | |---|---|---|---| | `dimensions` | `string[]` | `[]` | Up to 2 dimensions to group by | | `granularity` | `string` | none | Time bucketing: `minute`, `hour`, `day`, `week`, `month` | | `time_range` | `object` | last 7 days | `{ start, end }` as ISO 8601 UTC datetime strings. Seconds are required (`YYYY-MM-DDTHH:MM:SSZ`; fractional seconds allowed) — minute-precision values such as `2026-05-01T00:00Z` are rejected with 400. | | `filters` | `object[]` | `[]` | Up to 20 filter conditions | | `order_by` | `object` | time desc (if granularity set) | `{ field, direction }` where field is a metric, dimension, or `"date"` (short-form alias — maps to `date__day`, `date__hour`, etc. based on granularity) | | `limit` | `integer` | 1000 | Maximum total rows to return (1–10,000). On time-series queries with dimensions and no explicit `group_limit`, the server may raise this to accommodate the expected number of time-bucket/dimension combinations. | | `group_limit` | `integer` | auto-computed | Maximum rows per distinct dimension combination (ClickHouse LIMIT n BY). When omitted on time-series queries (granularity + dimensions), auto-computed from the time range to guarantee full time-window coverage per group. Explicit values override the default. Ignored when no dimensions are specified. | | `classifier_dimensions` | `object` | none | Group by dynamic classifier-produced dimensions. See [Classifier Dimensions](#classifier-dimensions) below. | | `classifier_filters` | `object` | none | Filter on classifier-produced dimension values. See [Classifier Filters](#classifier-filters) below. |

Filter Object Shape

{ "field": "<dimension_name>", "operator": "<op>", "value": "<value>" }

• 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
• `in` / `not_in` accept an optional `include_unset: true`, which also matches rows where the dimension has no value. Supported only on dimensions with an unset bucket (`api_key_id`, `app`, `user`) — otherwise the request is rejected with 400.
• 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.
• `workspace` — workspace UUID, not the workspace name shown in results.
• `app` — numeric app ID, not the app title shown in results.
• `model` — permaslug (e.g. `openai/gpt-4o`), not the display name.
• Other dimensions (`provider`, `origin`, `country`, `finish_reason`, `external_user`, etc.) are not enriched — filter values match what's returned in results.

Order By

{ "field": "<metric_or_dimension_or_date>", "direction": "asc" | "desc" }

When `granularity` is set and no `order_by` is specified, results are ordered by time descending.

Classifier Dimensions

Classifier dimensions allow grouping by dynamic, user-defined classification labels (e.g., topic, sentiment, category) produced by a classifier attached to your account.

{
  "classifier_dimensions": {
    "classifier_id": "550e8400-e29b-41d4-a716-446655440000",
    "dimension_names": ["category"],
    "include_nulls": false
  }
}

| Field | Type | Required | Description | |---|---|---|---| | `classifier_id` | `string` (UUID) | Yes | ID of the classifier (must belong to the caller's acco