Analytics - OpenRouter | Documentation

Overview

Analytics and usage endpoints

Available Operations

getUserActivity - Get user activity grouped by endpoint
getAnalyticsMeta - Get available analytics metrics and dimensions
queryAnalytics - Query analytics data

getUserActivity

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

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.analytics.getUserActivity();

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { analyticsGetUserActivity } from "@openrouter/sdk/funcs/analyticsGetUserActivity.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await analyticsGetUserActivity(openRouter);
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("analyticsGetUserActivity failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.GetUserActivityRequest	✔️	The request object to use for the request.
`options`	RequestOptions	➖	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<models.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	/

getAnalyticsMeta

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

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.analytics.getAnalyticsMeta();

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { analyticsGetAnalyticsMeta } from "@openrouter/sdk/funcs/analyticsGetAnalyticsMeta.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await analyticsGetAnalyticsMeta(openRouter);
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("analyticsGetAnalyticsMeta failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.GetAnalyticsMetaRequest	✔️	The request object to use for the request.
`options`	RequestOptions	➖	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<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	/

queryAnalytics

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

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.analytics.queryAnalytics({
    requestBody: {
      dimensions: [
        "model",
      ],
      granularity: "day",
      limit: 100,
      metrics: [
        "request_count",
      ],
      timeRange: {
        end: new Date("2025-01-08T00:00:00Z"),
        start: new Date("2025-01-01T00:00:00Z"),
      },
    },
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { analyticsQueryAnalytics } from "@openrouter/sdk/funcs/analyticsQueryAnalytics.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await analyticsQueryAnalytics(openRouter, {
    requestBody: {
      dimensions: [
        "model",
      ],
      granularity: "day",
      limit: 100,
      metrics: [
        "request_count",
      ],
      timeRange: {
        end: new Date("2025-01-08T00:00:00Z"),
        start: new Date("2025-01-01T00:00:00Z"),
      },
    },
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("analyticsQueryAnalytics failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.QueryAnalyticsRequest	✔️	The request object to use for the request.
`options`	RequestOptions	➖	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<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

​getUserActivity

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

​getAnalyticsMeta

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

​queryAnalytics

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

Overview

Available Operations

getUserActivity

Example Usage

Standalone function

Parameters

Response

Errors

getAnalyticsMeta

Example Usage

Standalone function

Parameters

Response

Errors

queryAnalytics

Example Usage

Standalone function

Parameters

Response

Errors