@ai-sdk/gateway 4.0.0-beta.23 → 4.0.0-beta.25

package/docs/00-ai-gateway.mdx

@@ -238,6 +238,86 @@ The `getCredits()` method returns your team's credit information based on the au
 - **balance** _number_ - Your team's current available credit balance
 - **total_used** _number_ - Total credits consumed by your team
 
+## Generation Lookup
+
+Look up detailed information about a specific generation by its ID, including cost, token usage, latency, and provider details. 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 in the stream without waiting for completion. This is especially useful in cases where a network interruption or mid-stream error could prevent you from receiving the final response — since the gateway records the final status server-side, you can use the generation ID to look up the results (including cost, token usage, and finish reason) later via `getGenerationInfo()`.
+
+```ts
+import { gateway, generateText } from 'ai';
+
+// Make a request
+const result = await generateText({
+  model: gateway('anthropic/claude-sonnet-4'),
+  prompt: 'Explain quantum entanglement briefly',
+});
+
+// Get the generation ID from provider metadata
+const generationId = result.providerMetadata?.gateway?.generationId;
+
+// Look up detailed generation info
+const generation = await gateway.getGenerationInfo({ id: generationId });
+
+console.log(`Model: ${generation.model}`);
+console.log(`Cost: $${generation.totalCost.toFixed(6)}`);
+console.log(`Latency: ${generation.latency}ms`);
+console.log(`Prompt tokens: ${generation.promptTokens}`);
+console.log(`Completion tokens: ${generation.completionTokens}`);
+```
+
+With `streamText`, you can capture the generation ID from the first chunk via `fullStream`:
+
+```ts
+import { gateway, streamText } from 'ai';
+
+const result = streamText({
+  model: gateway('anthropic/claude-sonnet-4'),
+  prompt: 'Explain quantum entanglement briefly',
+});
+
+let generationId: string | undefined;
+
+for await (const part of result.fullStream) {
+  if (!generationId && part.providerMetadata?.gateway?.generationId) {
+    generationId = part.providerMetadata.gateway.generationId as string;
+    console.log(`Generation ID (early): ${generationId}`);
+  }
+}
+
+// Look up cost and usage after the stream completes
+if (generationId) {
+  const generation = await gateway.getGenerationInfo({ id: generationId });
+  console.log(`Cost: $${generation.totalCost.toFixed(6)}`);
+  console.log(`Finish reason: ${generation.finishReason}`);
+}
+```
+
+The `getGenerationInfo()` method accepts:
+
+- **id** _string_ - The generation ID to look up (format: `gen_<ulid>`, required)
+
+It returns a `GatewayGenerationInfo` object with the following fields:
+
+- **id** _string_ - The generation ID
+- **totalCost** _number_ - Total cost in USD
+- **upstreamInferenceCost** _number_ - Upstream inference cost in USD (relevant for BYOK)
+- **usage** _number_ - Usage cost in USD (same as totalCost)
+- **createdAt** _string_ - ISO 8601 timestamp when the generation was created
+- **model** _string_ - Model identifier used
+- **isByok** _boolean_ - Whether Bring Your Own Key credentials were used
+- **providerName** _string_ - The provider that served this generation
+- **streamed** _boolean_ - Whether streaming was used
+- **finishReason** _string_ - Finish reason (e.g. `'stop'`)
+- **latency** _number_ - Time to first token in milliseconds
+- **generationTime** _number_ - Total generation time in milliseconds
+- **promptTokens** _number_ - Number of prompt tokens
+- **completionTokens** _number_ - Number of completion tokens
+- **reasoningTokens** _number_ - Reasoning tokens used (if applicable)
+- **cachedTokens** _number_ - Cached tokens used (if applicable)
+- **cacheCreationTokens** _number_ - Cache creation input tokens
+- **billableWebSearchCalls** _number_ - Number of billable web search calls
+
 ## Examples
 
 ### Basic Text Generation
@@ -561,11 +641,76 @@ 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
 
-#### Reporting API
+#### Querying Spend Reports
 
-You can query usage data programmatically using the [Custom Reporting API](https://vercel.com/docs/ai-gateway/capabilities/custom-reporting). The reporting API is only available for Vercel Pro and Enterprise plans. The API supports grouping by `model`, `user`, `tag`, `provider`, or `credential_type`, and filtering by date range, user, model, tags, and more.
+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).
 
-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
 

package/package.json

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

package/src/gateway-generation-info.ts

@@ -0,0 +1,147 @@
+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 GatewayGenerationInfoParams {
+  /** The generation ID to look up (format: gen_<ulid>) */
+  id: string;
+}
+
+export interface GatewayGenerationInfo {
+  /** The generation ID */
+  id: string;
+  /** Total cost in USD */
+  totalCost: number;
+  /** Upstream inference cost in USD (BYOK only) */
+  upstreamInferenceCost: number;
+  /** Usage cost in USD (same as totalCost) */
+  usage: number;
+  /** ISO 8601 timestamp when the generation was created */
+  createdAt: string;
+  /** Model identifier */
+  model: string;
+  /** Whether BYOK credentials were used */
+  isByok: boolean;
+  /** Provider that served this generation */
+  providerName: string;
+  /** Whether streaming was used */
+  streamed: boolean;
+  /** Finish reason (e.g. 'stop') */
+  finishReason: string;
+  /** Time to first token in milliseconds */
+  latency: number;
+  /** Total generation time in milliseconds */
+  generationTime: number;
+  /** Number of prompt tokens */
+  promptTokens: number;
+  /** Number of completion tokens */
+  completionTokens: number;
+  /** Reasoning tokens used */
+  reasoningTokens: number;
+  /** Cached tokens used */
+  cachedTokens: number;
+  /** Cache creation input tokens */
+  cacheCreationTokens: number;
+  /** Billable web search calls */
+  billableWebSearchCalls: number;
+}
+
+export class GatewayGenerationInfoFetcher {
+  constructor(private readonly config: GatewayConfig) {}
+
+  async getGenerationInfo(
+    params: GatewayGenerationInfoParams,
+  ): Promise<GatewayGenerationInfo> {
+    try {
+      const baseUrl = new URL(this.config.baseURL);
+
+      const { value } = await getFromApi({
+        url: `${baseUrl.origin}/v1/generation?id=${encodeURIComponent(params.id)}`,
+        headers: await resolve(this.config.headers()),
+        successfulResponseHandler: createJsonResponseHandler(
+          gatewayGenerationInfoResponseSchema,
+        ),
+        failedResponseHandler: createJsonErrorResponseHandler({
+          errorSchema: z.any(),
+          errorToMessage: data => data,
+        }),
+        fetch: this.config.fetch,
+      });
+
+      return value;
+    } catch (error) {
+      throw await asGatewayError(error);
+    }
+  }
+}
+
+const gatewayGenerationInfoResponseSchema = lazySchema(() =>
+  zodSchema(
+    z
+      .object({
+        data: z
+          .object({
+            id: z.string(),
+            total_cost: z.number(),
+            upstream_inference_cost: z.number(),
+            usage: z.number(),
+            created_at: z.string(),
+            model: z.string(),
+            is_byok: z.boolean(),
+            provider_name: z.string(),
+            streamed: z.boolean(),
+            finish_reason: z.string(),
+            latency: z.number(),
+            generation_time: z.number(),
+            native_tokens_prompt: z.number(),
+            native_tokens_completion: z.number(),
+            native_tokens_reasoning: z.number(),
+            native_tokens_cached: z.number(),
+            native_tokens_cache_creation: z.number(),
+            billable_web_search_calls: z.number(),
+          })
+          .transform(
+            ({
+              total_cost,
+              upstream_inference_cost,
+              created_at,
+              is_byok,
+              provider_name,
+              finish_reason,
+              generation_time,
+              native_tokens_prompt,
+              native_tokens_completion,
+              native_tokens_reasoning,
+              native_tokens_cached,
+              native_tokens_cache_creation,
+              billable_web_search_calls,
+              ...rest
+            }) => ({
+              ...rest,
+              totalCost: total_cost,
+              upstreamInferenceCost: upstream_inference_cost,
+              createdAt: created_at,
+              isByok: is_byok,
+              providerName: provider_name,
+              finishReason: finish_reason,
+              generationTime: generation_time,
+              promptTokens: native_tokens_prompt,
+              completionTokens: native_tokens_completion,
+              reasoningTokens: native_tokens_reasoning,
+              cachedTokens: native_tokens_cached,
+              cacheCreationTokens: native_tokens_cache_creation,
+              billableWebSearchCalls: billable_web_search_calls,
+            }),
+          ),
+      })
+      .transform(({ data }) => data),
+  ),
+);

package/src/gateway-provider.ts

@@ -13,6 +13,16 @@ import {
   type GatewayFetchMetadataResponse,
   type GatewayCreditsResponse,
 } from './gateway-fetch-metadata';
+import {
+  GatewaySpendReport,
+  type GatewaySpendReportParams,
+  type GatewaySpendReportResponse,
+} from './gateway-spend-report';
+import {
+  GatewayGenerationInfoFetcher,
+  type GatewayGenerationInfoParams,
+  type GatewayGenerationInfo,
+} from './gateway-generation-info';
 import { GatewayLanguageModel } from './gateway-language-model';
 import { GatewayEmbeddingModel } from './gateway-embedding-model';
 import { GatewayImageModel } from './gateway-image-model';
@@ -56,6 +66,22 @@ 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>;
+
+  /**
+   * Returns detailed information about a specific generation by its ID,
+   * including cost, token usage, latency, and provider details.
+   */
+  getGenerationInfo(
+    params: GatewayGenerationInfoParams,
+  ): Promise<GatewayGenerationInfo>;
+
   /**
    * Creates a model for generating text embeddings.
    */
@@ -253,6 +279,36 @@ 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 getGenerationInfo = async (params: GatewayGenerationInfoParams) => {
+    return new GatewayGenerationInfoFetcher({
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    })
+      .getGenerationInfo(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 +322,8 @@ export function createGatewayProvider(
   provider.specificationVersion = 'v4' as const;
   provider.getAvailableModels = getAvailableModels;
   provider.getCredits = getCredits;
+  provider.getSpendReport = getSpendReport;
+  provider.getGenerationInfo = getGenerationInfo;
   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,15 @@ 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 {
+  GatewayGenerationInfoParams,
+  GatewayGenerationInfo,
+} from './gateway-generation-info';
 export type { GatewayLanguageModelEntry as GatewayModelEntry } from './gateway-model-entry';
 export {
   createGatewayProvider,