@ai-sdk/gateway 4.0.0-beta.22 → 4.0.0-beta.24

package/docs/00-ai-gateway.mdx

@@ -533,12 +533,14 @@ for await (const part of result.fullStream) {
 }
 ```
 
-### Usage Tracking with User and Tags
+### Custom Reporting
 
-Track usage per end-user and categorize requests with tags:
+Track usage per end-user and categorize requests with tags, then query the data through the reporting API.
+
+#### Usage Tracking with User and Tags
 
 ```ts
-import type { GatewayLanguageModelOptions } from '@ai-sdk/gateway';
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
 import { generateText } from 'ai';
 
 const { text } = await generateText({
@@ -548,7 +550,7 @@ const { text } = await generateText({
     gateway: {
       user: 'user-abc-123', // Track usage for this specific end-user
       tags: ['document-summary', 'premium-feature'], // Categorize for reporting
-    } satisfies GatewayLanguageModelOptions,
+    } satisfies GatewayProviderOptions,
   },
 });
 ```
@@ -559,6 +561,77 @@ This allows you to:
 - Filter and analyze spending by feature or use case using tags
 - Track which users or features are driving the most AI usage
 
+#### Querying Spend Reports
+
+Use the `getSpendReport()` method to query usage data programmatically. The reporting API is only available for Vercel Pro and Enterprise plans. For pricing, see the [Custom Reporting docs](https://vercel.com/docs/ai-gateway/capabilities/custom-reporting).
+
+```ts
+import { gateway } from 'ai';
+
+const report = await gateway.getSpendReport({
+  startDate: '2026-03-01',
+  endDate: '2026-03-25',
+  groupBy: 'model',
+});
+
+for (const row of report.results) {
+  console.log(`${row.model}: $${row.totalCost.toFixed(4)}`);
+}
+```
+
+The `getSpendReport()` method accepts the following parameters:
+
+- **startDate** _string_ - Start date in `YYYY-MM-DD` format (inclusive, required)
+- **endDate** _string_ - End date in `YYYY-MM-DD` format (inclusive, required)
+- **groupBy** _string_ - Aggregation dimension: `'day'` (default), `'user'`, `'model'`, `'tag'`, `'provider'`, or `'credential_type'`
+- **datePart** _string_ - Time granularity when `groupBy` is `'day'`: `'day'` or `'hour'`
+- **userId** _string_ - Filter to a specific user
+- **model** _string_ - Filter to a specific model (e.g. `'anthropic/claude-sonnet-4.5'`)
+- **provider** _string_ - Filter to a specific provider (e.g. `'anthropic'`)
+- **credentialType** _string_ - Filter by `'byok'` or `'system'` credentials
+- **tags** _string[]_ - Filter to requests matching these tags
+
+Each row in `results` contains a grouping field (matching your `groupBy` choice) and metrics:
+
+- **totalCost** _number_ - Total cost in USD
+- **marketCost** _number_ - Market cost in USD
+- **inputTokens** _number_ - Number of input tokens
+- **outputTokens** _number_ - Number of output tokens
+- **cachedInputTokens** _number_ - Number of cached input tokens
+- **cacheCreationInputTokens** _number_ - Number of cache creation input tokens
+- **reasoningTokens** _number_ - Number of reasoning tokens
+- **requestCount** _number_ - Number of requests
+
+You can combine tracking and querying to analyze spend by tags you defined:
+
+```ts
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
+import { gateway, streamText } from 'ai';
+
+// 1. Make requests with tags
+const result = streamText({
+  model: gateway('anthropic/claude-haiku-4.5'),
+  prompt: 'Summarize this quarter's results',
+  providerOptions: {
+    gateway: {
+      tags: ['team:finance', 'feature:summaries'],
+    } satisfies GatewayProviderOptions,
+  },
+});
+
+// 2. Later, query spend filtered by those tags
+const report = await gateway.getSpendReport({
+  startDate: '2026-03-01',
+  endDate: '2026-03-31',
+  groupBy: 'tag',
+  tags: ['team:finance'],
+});
+
+for (const row of report.results) {
+  console.log(`${row.tag}: $${row.totalCost.toFixed(4)} (${row.requestCount} requests)`);
+}
+```
+
 ## Provider Options
 
 The AI Gateway provider accepts provider options that control routing behavior and provider-specific configurations.
@@ -568,7 +641,7 @@ The AI Gateway provider accepts provider options that control routing behavior a
 You can use the `gateway` key in `providerOptions` to control how AI Gateway routes requests:
 
 ```ts
-import type { GatewayLanguageModelOptions } from '@ai-sdk/gateway';
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
 import { generateText } from 'ai';
 
 const { text } = await generateText({
@@ -578,7 +651,7 @@ const { text } = await generateText({
     gateway: {
       order: ['vertex', 'anthropic'], // Try Vertex AI first, then Anthropic
       only: ['vertex', 'anthropic'], // Only use these providers
-    } satisfies GatewayLanguageModelOptions,
+    } satisfies GatewayProviderOptions,
   },
 });
 ```
@@ -642,7 +715,7 @@ The following gateway provider options are available:
 You can combine these options to have fine-grained control over routing and tracking:
 
 ```ts
-import type { GatewayLanguageModelOptions } from '@ai-sdk/gateway';
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
 import { generateText } from 'ai';
 
 const { text } = await generateText({
@@ -652,7 +725,7 @@ const { text } = await generateText({
     gateway: {
       order: ['vertex'], // Prefer Vertex AI
       only: ['anthropic', 'vertex'], // Only allow these providers
-    } satisfies GatewayLanguageModelOptions,
+    } satisfies GatewayProviderOptions,
   },
 });
 ```
@@ -662,7 +735,7 @@ const { text } = await generateText({
 The `models` option enables automatic fallback to alternative models when the primary model fails:
 
 ```ts
-import type { GatewayLanguageModelOptions } from '@ai-sdk/gateway';
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
 import { generateText } from 'ai';
 
 const { text } = await generateText({
@@ -671,7 +744,7 @@ const { text } = await generateText({
   providerOptions: {
     gateway: {
       models: ['openai/gpt-5-nano', 'gemini-2.0-flash'], // Fallback models
-    } satisfies GatewayLanguageModelOptions,
+    } satisfies GatewayProviderOptions,
   },
 });
 
@@ -689,7 +762,7 @@ that have zero data retention policies. When `zeroDataRetention` is `false` or n
 specified, there is no enforcement of restricting routing.
 
 ```ts
-import type { GatewayLanguageModelOptions } from '@ai-sdk/gateway';
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
 import { generateText } from 'ai';
 
 const { text } = await generateText({
@@ -698,7 +771,7 @@ const { text } = await generateText({
   providerOptions: {
     gateway: {
       zeroDataRetention: true,
-    } satisfies GatewayLanguageModelOptions,
+    } satisfies GatewayProviderOptions,
   },
 });
 ```
@@ -709,7 +782,7 @@ When using provider-specific options through AI Gateway, use the actual provider
 
 ```ts
 import type { AnthropicLanguageModelOptions } from '@ai-sdk/anthropic';
-import type { GatewayLanguageModelOptions } from '@ai-sdk/gateway';
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
 import { generateText } from 'ai';
 
 const { text } = await generateText({
@@ -718,7 +791,7 @@ const { text } = await generateText({
   providerOptions: {
     gateway: {
       order: ['vertex', 'anthropic'],
-    } satisfies GatewayLanguageModelOptions,
+    } satisfies GatewayProviderOptions,
     anthropic: {
       thinking: { type: 'enabled', budgetTokens: 12000 },
     } satisfies AnthropicLanguageModelOptions,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-sdk/gateway",
   "private": false,
-  "version": "4.0.0-beta.22",
+  "version": "4.0.0-beta.24",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

package/src/gateway-provider-options.ts

@@ -2,7 +2,7 @@ import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
 // https://vercel.com/docs/ai-gateway/provider-options
-const gatewayLanguageModelOptions = lazySchema(() =>
+const gatewayProviderOptions = lazySchema(() =>
   zodSchema(
     z.object({
       /**
@@ -75,6 +75,4 @@ const gatewayLanguageModelOptions = lazySchema(() =>
   ),
 );
 
-export type GatewayLanguageModelOptions = InferSchema<
-  typeof gatewayLanguageModelOptions
->;
+export type GatewayProviderOptions = InferSchema<typeof gatewayProviderOptions>;

package/src/gateway-provider.ts

@@ -13,6 +13,11 @@ import {
   type GatewayFetchMetadataResponse,
   type GatewayCreditsResponse,
 } from './gateway-fetch-metadata';
+import {
+  GatewaySpendReport,
+  type GatewaySpendReportParams,
+  type GatewaySpendReportResponse,
+} from './gateway-spend-report';
 import { GatewayLanguageModel } from './gateway-language-model';
 import { GatewayEmbeddingModel } from './gateway-embedding-model';
 import { GatewayImageModel } from './gateway-image-model';
@@ -56,6 +61,14 @@ export interface GatewayProvider extends ProviderV4 {
    */
   getCredits(): Promise<GatewayCreditsResponse>;
 
+  /**
+   * Returns a spend report with cost, token, and request count data,
+   * aggregated by the specified dimension.
+   */
+  getSpendReport(
+    params: GatewaySpendReportParams,
+  ): Promise<GatewaySpendReportResponse>;
+
   /**
    * Creates a model for generating text embeddings.
    */
@@ -253,6 +266,21 @@ export function createGatewayProvider(
       });
   };
 
+  const getSpendReport = async (params: GatewaySpendReportParams) => {
+    return new GatewaySpendReport({
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    })
+      .getSpendReport(params)
+      .catch(async (error: unknown) => {
+        throw await asGatewayError(
+          error,
+          await parseAuthMethod(await getHeaders()),
+        );
+      });
+  };
+
   const provider = function (modelId: GatewayModelId) {
     if (new.target) {
       throw new Error(
@@ -266,6 +294,7 @@ export function createGatewayProvider(
   provider.specificationVersion = 'v4' as const;
   provider.getAvailableModels = getAvailableModels;
   provider.getCredits = getCredits;
+  provider.getSpendReport = getSpendReport;
   provider.imageModel = (modelId: GatewayImageModelId) => {
     return new GatewayImageModel(modelId, {
       provider: 'gateway',

package/src/gateway-spend-report.ts

@@ -0,0 +1,191 @@
+import {
+  createJsonErrorResponseHandler,
+  createJsonResponseHandler,
+  getFromApi,
+  lazySchema,
+  resolve,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { asGatewayError } from './errors';
+import type { GatewayConfig } from './gateway-config';
+
+export interface GatewaySpendReportParams {
+  /** Start date in YYYY-MM-DD format (inclusive) */
+  startDate: string;
+  /** End date in YYYY-MM-DD format (inclusive) */
+  endDate: string;
+  /** Primary aggregation dimension. Defaults to 'day'. */
+  groupBy?: 'day' | 'user' | 'model' | 'tag' | 'provider' | 'credential_type';
+  /** Time granularity when groupBy is 'day'. */
+  datePart?: 'day' | 'hour';
+  /** Filter to a specific user's spend. */
+  userId?: string;
+  /** Filter to a specific model (e.g. 'anthropic/claude-sonnet-4.5'). */
+  model?: string;
+  /** Filter to a specific provider (e.g. 'anthropic'). */
+  provider?: string;
+  /** Filter to BYOK or system credentials. */
+  credentialType?: 'byok' | 'system';
+  /** Filter to requests with these tags. */
+  tags?: string[];
+}
+
+export interface GatewaySpendReportRow {
+  /** Date string (present when groupBy is 'day') */
+  day?: string;
+  /** Hour timestamp (present when groupBy is 'day' and datePart is 'hour') */
+  hour?: string;
+  /** User identifier (present when groupBy is 'user') */
+  user?: string;
+  /** Model identifier (present when groupBy is 'model') */
+  model?: string;
+  /** Tag value (present when groupBy is 'tag') */
+  tag?: string;
+  /** Provider name (present when groupBy is 'provider') */
+  provider?: string;
+  /** Credential type (present when groupBy is 'credential_type') */
+  credentialType?: 'byok' | 'system';
+
+  /** Total cost in USD */
+  totalCost: number;
+  /** Market cost in USD */
+  marketCost?: number;
+  /** Number of input tokens */
+  inputTokens?: number;
+  /** Number of output tokens */
+  outputTokens?: number;
+  /** Number of cached input tokens */
+  cachedInputTokens?: number;
+  /** Number of cache creation input tokens */
+  cacheCreationInputTokens?: number;
+  /** Number of reasoning tokens */
+  reasoningTokens?: number;
+  /** Number of requests */
+  requestCount?: number;
+}
+
+export interface GatewaySpendReportResponse {
+  results: GatewaySpendReportRow[];
+}
+
+export class GatewaySpendReport {
+  constructor(private readonly config: GatewayConfig) {}
+
+  async getSpendReport(
+    params: GatewaySpendReportParams,
+  ): Promise<GatewaySpendReportResponse> {
+    try {
+      const baseUrl = new URL(this.config.baseURL);
+
+      const searchParams = new URLSearchParams();
+      searchParams.set('start_date', params.startDate);
+      searchParams.set('end_date', params.endDate);
+
+      if (params.groupBy) {
+        searchParams.set('group_by', params.groupBy);
+      }
+      if (params.datePart) {
+        searchParams.set('date_part', params.datePart);
+      }
+      if (params.userId) {
+        searchParams.set('user_id', params.userId);
+      }
+      if (params.model) {
+        searchParams.set('model', params.model);
+      }
+      if (params.provider) {
+        searchParams.set('provider', params.provider);
+      }
+      if (params.credentialType) {
+        searchParams.set('credential_type', params.credentialType);
+      }
+      if (params.tags && params.tags.length > 0) {
+        searchParams.set('tags', params.tags.join(','));
+      }
+
+      const { value } = await getFromApi({
+        url: `${baseUrl.origin}/v1/report?${searchParams.toString()}`,
+        headers: await resolve(this.config.headers()),
+        successfulResponseHandler: createJsonResponseHandler(
+          gatewaySpendReportResponseSchema,
+        ),
+        failedResponseHandler: createJsonErrorResponseHandler({
+          errorSchema: z.any(),
+          errorToMessage: data => data,
+        }),
+        fetch: this.config.fetch,
+      });
+
+      return value;
+    } catch (error) {
+      throw await asGatewayError(error);
+    }
+  }
+}
+
+const gatewaySpendReportResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      results: z.array(
+        z
+          .object({
+            day: z.string().optional(),
+            hour: z.string().optional(),
+            user: z.string().optional(),
+            model: z.string().optional(),
+            tag: z.string().optional(),
+            provider: z.string().optional(),
+            credential_type: z.enum(['byok', 'system']).optional(),
+            total_cost: z.number(),
+            market_cost: z.number().optional(),
+            input_tokens: z.number().optional(),
+            output_tokens: z.number().optional(),
+            cached_input_tokens: z.number().optional(),
+            cache_creation_input_tokens: z.number().optional(),
+            reasoning_tokens: z.number().optional(),
+            request_count: z.number().optional(),
+          })
+          .transform(
+            ({
+              credential_type,
+              total_cost,
+              market_cost,
+              input_tokens,
+              output_tokens,
+              cached_input_tokens,
+              cache_creation_input_tokens,
+              reasoning_tokens,
+              request_count,
+              ...rest
+            }) => ({
+              ...rest,
+              ...(credential_type !== undefined
+                ? { credentialType: credential_type }
+                : {}),
+              totalCost: total_cost,
+              ...(market_cost !== undefined ? { marketCost: market_cost } : {}),
+              ...(input_tokens !== undefined
+                ? { inputTokens: input_tokens }
+                : {}),
+              ...(output_tokens !== undefined
+                ? { outputTokens: output_tokens }
+                : {}),
+              ...(cached_input_tokens !== undefined
+                ? { cachedInputTokens: cached_input_tokens }
+                : {}),
+              ...(cache_creation_input_tokens !== undefined
+                ? { cacheCreationInputTokens: cache_creation_input_tokens }
+                : {}),
+              ...(reasoning_tokens !== undefined
+                ? { reasoningTokens: reasoning_tokens }
+                : {}),
+              ...(request_count !== undefined
+                ? { requestCount: request_count }
+                : {}),
+            }),
+          ),
+      ),
+    }),
+  ),
+);

package/src/index.ts

@@ -5,6 +5,11 @@ export type {
   GatewayLanguageModelSpecification,
 } from './gateway-model-entry';
 export type { GatewayCreditsResponse } from './gateway-fetch-metadata';
+export type {
+  GatewaySpendReportParams,
+  GatewaySpendReportRow,
+  GatewaySpendReportResponse,
+} from './gateway-spend-report';
 export type { GatewayLanguageModelEntry as GatewayModelEntry } from './gateway-model-entry';
 export {
   createGatewayProvider,
@@ -16,9 +21,9 @@ export type {
   GatewayProviderSettings,
 } from './gateway-provider';
 export type {
-  GatewayLanguageModelOptions,
-  /** @deprecated Use `GatewayLanguageModelOptions` instead. */
-  GatewayLanguageModelOptions as GatewayProviderOptions,
+  GatewayProviderOptions,
+  /** @deprecated Use `GatewayProviderOptions` instead. */
+  GatewayProviderOptions as GatewayLanguageModelOptions,
 } from './gateway-provider-options';
 export {
   GatewayError,