@ai-sdk/gateway 3.0.82 → 3.0.83

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-sdk/gateway",
   "private": false,
-  "version": "3.0.82",
+  "version": "3.0.83",
   "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

@@ -18,6 +18,11 @@ import {
   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';
@@ -69,6 +74,14 @@ export interface GatewayProvider extends ProviderV3 {
     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.
    */
@@ -281,6 +294,21 @@ export function createGatewayProvider(
       });
   };
 
+  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(
@@ -295,6 +323,7 @@ export function createGatewayProvider(
   provider.getAvailableModels = getAvailableModels;
   provider.getCredits = getCredits;
   provider.getSpendReport = getSpendReport;
+  provider.getGenerationInfo = getGenerationInfo;
   provider.imageModel = (modelId: GatewayImageModelId) => {
     return new GatewayImageModel(modelId, {
       provider: 'gateway',

package/src/index.ts

@@ -10,6 +10,10 @@ export type {
   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,