Analytics - OpenRouter | Documentation

Overview

Analytics and usage endpoints

Available Operations

get_user_activity - Get user activity grouped by endpoint
get_analytics_meta - Get available analytics metrics and dimensions
query_analytics - Query analytics data

get_user_activity

Returns user activity data grouped by endpoint for the last 30 (completed) UTC days. Pass workspace_id to scope the response to a single workspace. Pass group_by=workspace to split each row per workspace and include workspace_id on every item; by default rows are aggregated across workspaces and workspace_id is not returned. Activity recorded before workspace resolution existed is permanently attributed to the account default workspace (no backfill is possible). A workspace-scoped management key needs activity:view_all on its own workspace and reads only that workspace: an omitted workspace_id defaults to it, a workspace_id naming any other workspace returns 403, api_key_hash and user_id resolve only keys and members of that workspace, and legacy activity with no workspace is excluded (including for the default workspace). Management key required.

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.analytics.get_user_activity()

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`request`	operations.GetUserActivityRequest	✔️	The request object to use for the request.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.ActivityResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.NotFoundResponseError	404	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

get_analytics_meta

Returns the available metrics, dimensions, filter operators, and granularities for the analytics query endpoint. Workspace-scoped management keys are accepted. Management key required.

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.analytics.get_analytics_meta()

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`http_referer`	Optional[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_title`	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	➖	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetAnalyticsMetaResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

query_analytics

Execute an analytics query with specified metrics, dimensions, filters, and time range. A workspace-scoped management key needs activity:view_all on its own workspace and reads only that workspace: it is refused a workspace filter naming another workspace, it excludes legacy rows with no workspace (including for the default workspace), and possible-cache metrics such as possible_cached_tokens return 400. Management key required.

Example Usage

from openrouter import OpenRouter
from openrouter.utils import parse_datetime
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.analytics.query_analytics(metrics=[
        "request_count",
    ], dimensions=[
        "model",
    ], granularity="day", limit=100, time_range={
        "end": parse_datetime("2025-01-08T00:00:00Z"),
        "start": parse_datetime("2025-01-01T00:00:00Z"),
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`metrics`	List[str]	✔️	N/A
`http_referer`	Optional[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_title`	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	➖	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`classifier_dimensions`	Optional[operations.ClassifierDimensions]	➖	Group results by custom classifier tags, breaking down metrics by the specified dimension values. Requires an active classifier on the workspace.
`classifier_filters`	Optional[operations.ClassifierFilters]	➖	Filter results to generations with specific classifier tag values. Can be combined with classifier_dimensions (must use the same classifier_id) or used independently with standard dimensions.
`dimensions`	List[str]	➖	N/A
`filters`	List[components.Filter]	➖	N/A
`granularity`	Optional[str]	➖	Time granularity	day
`group_limit`	Optional[int]	➖	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.	100
`limit`	Optional[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_by`	Optional[operations.OrderBy]	➖	N/A
`time_range`	Optional[operations.TimeRange]	➖	N/A
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.QueryAnalyticsResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.RequestTimeoutResponseError	408	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

​Overview

​Available Operations

​get_user_activity

​Example Usage

​Parameters

​Response

​Errors

​get_analytics_meta

​Example Usage

​Parameters

​Response

​Errors

​query_analytics

​Example Usage

​Parameters

​Response

​Errors

Overview

Available Operations

get_user_activity

Example Usage

Parameters

Response

Errors

get_analytics_meta

Example Usage

Parameters

Response

Errors

query_analytics

Example Usage

Parameters

Response

Errors