Custom Classifiers

Custom classifiers let you define a structured taxonomy and use a model of your choosing (OpenRouter will recommend fast, inexpensive models during classifier setup) to tag and classify your prompts. The classifier model runs asynchronously after each request completes (zero added latency), tagging generations with dimensions like department, task type, complexity, or anything you can think of. Tags appear in your logs, and roll-up reporting is available in your activity view. Together, these help you understand how AI is being used across your organization.

Getting Started

Navigate to your workspace’s classifiers page: Classifiers
Click Create classifier
Pick a preset or build your own from scratch
Optionally, pick a sampling rate (e.g. you may not want to classify 100% of the requests in the workspace)
Save and activate the classifier

Generations in that workspace will now be classified by the selected model. Open any generation in your logs to see its classification tags.

Only workspace admins and org admins can create and manage classifiers. Members can’t. Each workspace has its own independent classifier.

Classification Presets

Presets are templatized classifiers that you can use as a starting point to customize to your use case, or use as-is. Each comes with a tuned prompt, pre-selected dimensions, and sensible defaults.

Preset	What it does
Department	Tags each request by business function: Engineering, Sales, Marketing, Legal, HR, Finance, Operations
Audience	Tags by who the output is for: Internal, Client-facing, Regulator, Public
Engineering work	Tags by work type: Feature development, Bug fixing, Documentation, Refactoring, Code review, etc.
Agent complexity	Two dimensions: `difficulty_tier` (7 levels from trivial tool calls to frontier-expert work) and `task_family` (10 categories like coding, analysis, planning)
Capitalizable software expense	You will need to give additional information about which projects and activities are capitalizable. Customers are responsible for the accuracy of any final financial or tax data submitted or shared with third parties.

Build Your Own

If the presets don’t fit, build a classifier from scratch with up to eight individual dimensions per classifier.

What is Being Classified?

Before classification, the prompt is serialized into a single labeled transcript inside one user message e.g.:

SYSTEM: <caller system prompt>
TOOLS: search_web, run_sql, send_email
USER: <first user message>
ASSISTANT: <…>
TOOL_CALL run_sql: <args>
TOOL_RESULT: <…>
USER: <latest user message>

Note that:

The full tool schema is not sent; just the tool names.
Each turn is truncated to a maximum of 5,000 characters. If a turn is truncated, the text will end in ...[truncated] so that classifier understands the text would have continued.
If the classifier model has a meaningfully shorter context than the prompt in question, the classification will fail without affecting the original request. We recommend selecting a model with a large context window.

How Classification Works

Classification runs asynchronously after each generation completes:

Your request finishes and the response returns to your app (zero added latency)
A classification job is enqueued with a serialized version of your prompt
The classifier model evaluates the message against your taxonomy using structured outputs
Tags are written to the generation record and appear in your logs

The classifier model is called with a serialized version of your prompt, your classification prompt, and a structured output schema that constrains the response to your declared dimensions and values.

Billing

Classifier tokens bill like any other generation against your workspace’s credits. You control cost through model choice: picking a small, fast model (like Haiku or Flash) keeps classification costs low. Classification requests are billed against the administrative user who configured the classifier (and not against a particular API key).

Failure Handling

If classification fails (timeout, model error, invalid output), the generation proceeds normally with no tags written. Classification failures don’t affect your API responses.

Viewing Classifications

Classification tags appear in two places:

Log rows. Classified generations show a tag icon. Hover for a tooltip summary.
Generation detail panel. Open any classified generation to see a Classifications section with the full dimension-to-value breakdown.

For organization accounts, only org admins can see classification tags on log rows and in the generation detail panel. Workspace admins who aren’t org admins can create and manage classifiers but don’t see the resulting tags. Filter and analyze your classified generations in the Activity and Logs views, or with the API.

Query classifications with the API

To read classification tags programmatically, use the Analytics query endpoint (POST /api/v1/analytics/query). It’s the same query that powers the Activity Explore view, and it requires a management API key. Two request fields work with classifiers:

Field	What it does
`classifier_dimensions`	Groups results by classifier tags. Set `classifier_id`, and optionally `dimension_names` (up to two) to return each dimension as its own column. Set `include_nulls: true` to also include generations that have no tag from this classifier.
`classifier_filters`	Limits results to generations with specific tag values. Set `classifier_id` and a list of `filters`, each with a `field` (dimension name), an `operator` (`eq`, `neq`, `in`, or `not_in`), and a `value`. When you use it together with `classifier_dimensions`, both must use the same `classifier_id`.

You can combine both fields with the standard metrics, dimensions, filters, and granularity fields. For the full request and response schema, see the Analytics query endpoint reference.

Find your classifier ID

The API identifies a classifier by its UUID. To find it, open your workspace’s Classifiers page and click one of the classifier’s dimension badges. The Activity Explore page opens with a dimension query parameter in the URL in the form clf::<classifier_id>::<dimension_name>. The UUID between clf:: and the next :: is your classifier ID.

Get the tags for each generation

To list the tags for individual generations, group by the generation_id dimension and the classifier dimensions you want:

curl https://openrouter.ai/api/v1/analytics/query \
  -H "Authorization: Bearer $OPENROUTER_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["total_usage"],
    "dimensions": ["generation_id"],
    "classifier_dimensions": {
      "classifier_id": "<classifier_id>",
      "dimension_names": ["department"]
    },
    "time_range": {
      "start": "2026-10-01T00:00:00Z",
      "end": "2026-10-02T00:00:00Z"
    },
    "limit": 1000
  }'

Each row in data.data has a generation_id, a department key with that generation’s tag, and the requested metrics. Use the generation_id with GET /api/v1/generation to fetch the rest of the generation’s metadata.

Break down usage by tag

To see spend and request volume per tag value, drop generation_id and group by the classifier dimension instead. This example also limits the results to two departments:

curl https://openrouter.ai/api/v1/analytics/query \
  -H "Authorization: Bearer $OPENROUTER_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["request_count", "total_usage"],
    "classifier_dimensions": {
      "classifier_id": "<classifier_id>",
      "dimension_names": ["department"]
    },
    "classifier_filters": {
      "classifier_id": "<classifier_id>",
      "filters": [
        { "field": "department", "operator": "in", "value": ["Engineering", "Sales"] }
      ]
    },
    "granularity": "day",
    "time_range": {
      "start": "2026-10-01T00:00:00Z",
      "end": "2026-10-08T00:00:00Z"
    }
  }'

Classification runs asynchronously after each generation completes, so the most recent generations might not have tags yet. Generations that the classifier skipped because of its sampling rate never get tags from it.

Workspace Scoping

Each classifier is scoped to a single workspace. Different workspaces can have different classifiers (or none at all). This lets you run a department classifier on your org-wide workspace while a specific project workspace uses a task-type classifier.

Tips

Start with a preset. The Department and Engineering work presets cover the most common use cases. You can customize them later.
Use a cheap model. Classification prompts are short and well-constrained. Small/inexpensive models with large context windows work best and keep costs minimal.
Check coverage in your logs. After enabling a classifier, look at recent generations in your logs to verify tags are appearing as expected.

Overview

Models & Routing

Tool Calling

Features

Observability

Authentication

Ori

Developer Tools

Privacy

Best Practices

Community

Getting Started

Classification Presets

Build Your Own

What is Being Classified?

How Classification Works

Billing

Failure Handling

Viewing Classifications

Query classifications with the API

Find your classifier ID

Get the tags for each generation

Break down usage by tag

Workspace Scoping

Tips

​Getting Started

​Classification Presets

​Build Your Own

​What is Being Classified?

​How Classification Works

​Billing

​Failure Handling

​Viewing Classifications

​Query classifications with the API

​Find your classifier ID

​Get the tags for each generation

​Break down usage by tag

​Workspace Scoping

​Tips

Getting Started

Classification Presets

Build Your Own

What is Being Classified?

How Classification Works

Billing

Failure Handling

Viewing Classifications

Query classifications with the API

Find your classifier ID

Get the tags for each generation

Break down usage by tag

Workspace Scoping

Tips