Beta.Analytics - Python SDK

Beta.Analytics method reference

The Python SDK and docs are currently in beta. Report issues on GitHub.

Overview

beta.Analytics endpoints

Available Operations

get_analytics_meta

Returns the available metrics, dimensions, filter operators, and granularities for the analytics query endpoint. Management key required.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with OpenRouter(
5 http_referer="<value>",
6 x_open_router_title="<value>",
7 x_open_router_categories="<value>",
8 api_key=os.getenv("OPENROUTER_API_KEY", ""),
9) as open_router:
10
11 res = open_router.beta.analytics.get_analytics_meta()
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescription
http_refererOptional[str]The app identifier should be your app’s URL and is used as the primary identifier for rankings.
This is used to track API usage per application.
x_open_router_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.GetAnalyticsMetaResponse

Errors

Error TypeStatus CodeContent Type
errors.UnauthorizedResponseError401application/json
errors.ForbiddenResponseError403application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

query_analytics

Execute an analytics query with specified metrics, dimensions, filters, and time range. Management key required.

Example Usage

1from openrouter import OpenRouter
2from openrouter.utils import parse_datetime
3import os
4
5with OpenRouter(
6 http_referer="<value>",
7 x_open_router_title="<value>",
8 x_open_router_categories="<value>",
9 api_key=os.getenv("OPENROUTER_API_KEY", ""),
10) as open_router:
11
12 res = open_router.beta.analytics.query_analytics(metrics=[
13 "request_count",
14 ], dimensions=[
15 "model",
16 ], granularity="day", limit=100, time_range={
17 "end": parse_datetime("2025-01-08T00:00:00Z"),
18 "start": parse_datetime("2025-01-01T00:00:00Z"),
19 })
20
21 # Handle response
22 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
metricsList[str]✔️N/A
http_refererOptional[str]The app identifier should be your app’s URL and is used as the primary identifier for rankings.
This is used to track API usage per application.
x_open_router_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
dimensionsList[str]N/A
filtersList[operations.Filter]N/A
granularityOptional[str]Time granularityday
group_limitOptional[int]Maximum rows per distinct combination of dimensions (ClickHouse LIMIT n BY). 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.100
limitOptional[int]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.
order_byOptional[operations.OrderBy]N/A
time_rangeOptional[operations.TimeRange]N/A
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.QueryAnalyticsResponse

Errors

Error TypeStatus CodeContent Type
errors.BadRequestResponseError400application/json
errors.UnauthorizedResponseError401application/json
errors.ForbiddenResponseError403application/json
errors.RequestTimeoutResponseError408application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*