Custom Reporting

The Custom Reporting API gives you detailed visibility into your AI Gateway usage. You can break down costs and token consumption by model, user, tag, provider, or credential type to understand exactly where your AI spend is going.

Track costs by model: See how much you're spending on each model and compare cost efficiency across providers
Monitor per-user usage: Identify which users are driving the most spend and token consumption
Analyze by tags: Tag requests by feature, environment, or team to attribute costs and track usage across your organization
Compare providers: Understand cost and usage differences between providers serving the same models
Audit BYOK vs system credentials: Break down usage by credential type to see the impact of bring-your-own-key requests

Pricing

Charge type

Write

Query

Cost

$0.075 / 1,000 tag/user ID writes

$5 / 1,000 queries to the reporting endpoint

Applying user and tag info to requests

To use reporting, attach a user and/or tags to your AI Gateway requests. You can do this through the AI SDK, Chat Completions API, Responses API, OpenResponses API, or Anthropic Messages API. For Chat Completions, the standard user field supplies the reporting user when providerOptions.gateway.user is not set.

These examples use AI SDK 7 and the AI SDK for Python beta. Set AI_GATEWAY_API_KEY before running them. See API format differences for setup, request fields, and response handling.

AI SDK

See the AI SDK usage-tracking reference for SDK configuration and usage.

TypeScript

const { text } =awaitgenerateText({

Responses / OpenResponses

Python (beta)

model:'anthropic/claude-sonnet-5',

Messages API

Chat Completions

prompt:'Tell me about San Francisco.',

import { generateText } from'ai';

providerOptions: {

gateway: {

tags: ['feature:chat','env:development'],

},

});

user:'user-123',

console.log(text);

Using HTTP headers

You can also send reporting metadata as HTTP headers instead of (or in addition to) providerOptions.gateway. This is useful when a platform or proxy layer stamps context onto traffic without modifying application code:

Header

ai-reporting-tags

Type

string

Behavior when the request body also sets the same field

Comma-separated list. Merged with providerOptions.gateway.tags (deduped union).

ai-reporting-user

Request examples

string

Validation limits match the body schema: up to 10 tags total after merging header and body values (deduped), with each tag between 1 and 64 characters; user up to 256 characters. An invalid header returns HTTP 400.

Single value. OverwritesproviderOptions.gateway.user when present.

Both headers work across AI Gateway endpoints that accept providerOptions.gateway, including the formats shown below. The defaultHeaders / default_headers pattern on the SDK client is the same regardless of which endpoint you call. Swap in responses.create, messages.create, embeddings, image generation, or other supported calls as needed.

AI SDK

'ai-reporting-tags':'team:billing,feature:chat,env:development',

TypeScript

Python (beta)

const { text } =awaitgenerateText({

'ai-reporting-user':'user-12345',

prompt:'Explain quantum computing in two sentences.',

headers: {

console.log(text);

});

import { generateText } from'ai';

model:'anthropic/claude-sonnet-5',

Custom Reporting API reference

The reporting endpoint is available on Pro and Enterprise plans. The team is inferred from the API key or OIDC token. Hobby and Pro-trial plans cannot use this endpoint.

Endpoint

GET https://ai-gateway.vercel.sh/v1/report

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: BearerYOUR_API_KEY

Required query parameters

Parameter

start_date

Type

string

Description

Start date in YYYY-MM-DD format

end_date

Grouping

string

Optional query parameters

End date in YYYY-MM-DD format

Dates are inclusive (both start_date and end_date are included) and in UTC.

Parameter

Type

group_by

string

Options

day (default), user, model, tag, provider, credential_type, zero_data_retention, api_key_name

Description

How to aggregate the results. Each row represents one bucket of this dimension.

date_part

Filtering

string

Filters are applied before aggregation. Combine them with any group_by value.

day (default), hour

Time granularity. Only applies when group_by=day. Use hour for per-hour rows, day for per-day rows.

Parameter

Filter by a stable API key ID. Use self for the AI Gateway API key that authenticated the report request.

api_key_id

user_id string

Filter by one or more comma-separated tags. By default, requests match when they contain any listed tag.

Start Now

provider
credential_type
zero_data_retention
tags_match

Description

boolean Filter by a specific user ID

Filter to Zero Data Retention (ZDR)-requested vs non-ZDR requests

Start Now

Filter by credential type
Filter by provider
string
string

Filter by a specific model in creator/model-name format

openai

Example user_123

anthropic/claude-sonnet-5

abc123 or self
byok or system
true or false
production or production,api

any or all

API key names are not unique, so use the stable key ID when filtering. List the team's API keys to find each key's id. If you omit api_key_id, the report includes spend across the team. self requires AI Gateway API key authentication. The API returns a 400 response if you use self with an OIDC token, personal access token, or app token.

Example request

curl "https://ai-gateway.vercel.sh/v1/report?start_date=2026-01-01&end_date=2026-01-31&group_by=model"

-H"Authorization: Bearer $AI_GATEWAY_API_KEY"

Response format

The API returns a JSON object with a results array. Each row contains the one grouping field that matches the group_by parameter you used, plus the aggregated metrics. The example below shows every possible field together so you can see the shape; in a real response, only the grouping field for your selected group_by will be present. It can take a few minutes for requests to appear in the reporting endpoint.

"model":"anthropic/claude-sonnet-5",

"credential_type":"system",

"zero_data_retention":"false",

"user":"user_123",

{

"provider":"anthropic",

"tag":"production",

"results": [

"api_key_name":"Production key",

"market_cost":12.0,

"surcharge_cost":0.5,

"total_cost":10.5,

"cached_input_tokens":200,

"gateway_cost":0,

"cache_creation_input_tokens":50,

"input_tokens":1000,

"output_tokens":500,

"reasoning_tokens":100,

"request_count":25

Response fields

Every row includes a single grouping field that depends on group_by, plus the metrics below.

Grouping fields

Present when

A single tag value (one row per tag in the request)

credential_type

group_by=day and date_part=day (default)

group_by=user

string

group_by=provider

string

api_key_name

group_by=day and date_part=hour

group_by=model

group_by=tag

string

byok or system

zero_data_retention

The human-readable name of the API key that served the request

string

true or false

string

Metric fields

market_cost

Market price of the request at the time it ran. Includes both BYOK and non-BYOK cost.

cached_input_tokens

Surcharge portion of total_cost (for example, from add-on capabilities).

Input tokens used

number

Output tokens used

number

surcharge_cost

AI Gateway's own cost, separate from the provider rate.

output_tokens

gateway_cost

Description

Reasoning tokens

reasoning_tokens

Number of requests in this row

number

input_tokens

Cached input tokens

request_count

endDate:'2026-03-25',

startDate:'2026-03-01',

import { gateway } from'ai';

Query spend reports with the AI SDK's getSpendReport() method. It accepts the same parameters as the REST API (in camelCase) and returns camelCase results.

constreport=awaitgateway.getSpendReport({

All cost values are in USD and aggregated based on the grouping parameter.

});

}

groupBy:'model',

console.log(`${row.model}: $${row.totalCost.toFixed(4)}`);

for (constrowofreport.results) {

You can combine tagging on requests with filtered queries to attribute costs by feature, team, or environment:

providerOptions: {

import { gateway, streamText } from'ai';

gateway: {

importtype { GatewayProviderOptions } from'@ai-sdk/gateway';

// 1. Make requests with tags

});

model:'anthropic/claude-opus-5',

},

constresult=streamText({

// 2. Later, query spend filtered by those tags

} satisfiesGatewayProviderOptions,

endDate:'2026-03-31',

});

startDate:'2026-03-01',

groupBy:'tag',

constreport=awaitgateway.getSpendReport({

);

console.log(

tags: ['team:finance'],

}

See the AI SDK docs on spend reports for the full list of parameters and response fields.

Generation lookup

Use the AI SDK's getGenerationInfo() method to look up a specific generation by its ID, including cost, token usage, latency, and provider details. For the dedicated workflow and REST API links, see Generation Lookup. Generation IDs are available in providerMetadata.gateway.generationId on both generateText and streamText responses.

When streaming, the generation ID is injected on the first content chunk, so you can capture it early without waiting for completion. This is useful when a network interruption cuts off the final response. AI Gateway records the final status server-side, so you can use the generation ID to look up the results later.

generateText

import { gateway, generateText } from'ai';

});

console.log(`Cost: $${generation.totalCost.toFixed(6)}`);

model:'anthropic/claude-opus-5',

constgenerationId=result.providerMetadata?.gateway?.generationId;

prompt:'Explain quantum entanglement briefly',

if (typeof generationId !=='string') thrownewError('Missing generation ID');

constresult=awaitgenerateText({

console.log(`Prompt tokens: ${generation.promptTokens}`);

console.log(`Model: ${generation.model}`);

console.log(`Completion tokens: ${generation.completionTokens}`);

console.log(`Latency: ${generation.latency}ms`);

constgeneration=awaitgateway.getGenerationInfo({ id: generationId });

See the AI SDK docs on generation lookup for the full list of response fields.

REST API usage examples

Group by day

curl "https://ai-gateway.vercel.sh/v1/report?start_date=2026-01-01&end_date=2026-01-31&date_part=day"