---
title: "Query analytics data"
method: POST
path: "/analytics/query"
tags: ["beta.Analytics"]
---

# Query analytics data

`POST /analytics/query`

Execute an analytics query with specified metrics, dimensions, filters, and time range. [Management key](/docs/guides/overview/auth/management-api-keys) required.

## Request body

- object
  - `dimensions` string[]
  - `filters` object[]
    - `field` string, required — Dimension to filter on. Use the /meta endpoint for available dimensions.
    - `operator` string, required — Filter operator
    - `value` union, required — Filter value (scalar or array depending on operator). Several dimensions are enriched in responses (returned as human-readable labels), but filters must use the underlying ID: `api_key_id` — numeric ID (from generation metadata) or key hash (64-char hex from GET /api/v1/keys, resolved server-side); `user` — Clerk user ID (e.g. "user_abc123"), not the display name; `workspace` — workspace UUID, not the workspace name; `app` — numeric app ID, not the app title; `model` — permaslug (e.g. "openai/gpt-4o"), not the display name. Other dimensions (provider, origin, country, etc.) are not enriched and accept the value as returned.
      - string
      - number, double
      - union[]
        - union
          - string
          - number, double
  - `granularity` string — Time granularity
  - `group_limit` integer — Maximum rows per distinct combination of dimensions. When omitted on time-series queries (granularity + dimensions), auto-computed to avoid truncating time windows. Explicit values override the default and may truncate time buckets if set lower than the number of buckets in the range. Ignored when no dimensions are specified.
  - `limit` integer — Maximum total rows returned. Defaults to 1000. On time-series queries with dimensions and no explicit group_limit, the server may raise this to accommodate the expected number of unique time-bucket/dimension combinations.
  - `metrics` string[], required
  - `order_by` object
    - `direction` 'asc' | 'desc', required
    - `field` string, required — Field to order by
  - `time_range` object
    - `end` string, date-time, required
    - `start` string, date-time, required

## Response `200`

Analytics query results

- object
  - `data` object, required
    - `cachedAt` number, double
    - `data` object[], required
    - `metadata` object, required
      - `query_time_ms` number, double, required
      - `row_count` integer, required
      - `truncated` boolean, required
    - `warnings` string[] — Warnings about filter resolution issues (e.g. unresolvable api_key_id hashes). The query still runs normally; these inform the caller that some filter values could not be resolved.

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed input
- `401` — Unauthorized - Authentication required or invalid credentials
- `403` — Forbidden - Authentication successful but insufficient permissions
- `408` — Request Timeout - Operation exceeded time limit
- `500` — Internal Server Error - Unexpected server error

## Changes

- **2026-06-16** `7d53485769cf` — 1 info
  - added the optional property `data/warnings` to the response with the `200` status

[Change history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/analytics/query/post.md)

---

[API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openrouterteam/openrouter-api/revisions/38c52b02b5f0/schema)