@ai-sdk/gateway 4.0.63 → 4.0.67

package/docs/00-ai-gateway.mdx

@@ -207,6 +207,200 @@ const { text } = await generateText({
 
 AI Gateway language models can also be used in the `streamText` function and support structured data generation with [`Output`](/docs/reference/ai-sdk-core/output) (see [AI SDK Core](/docs/ai-sdk-core)).
 
+When an upstream provider reports a well-formed error after streaming has
+started, AI SDK Core exposes it as a
+[`StreamProviderError`](/docs/reference/ai-sdk-errors/ai-stream-provider-error).
+Use its `type`, `code`, `statusCode`, and `isRetryable` metadata to classify
+the failure without inspecting the Gateway's serialized error payload.
+
+## Text Batches
+
+<Note type="warning">
+  Text batch support is experimental and the API may change in patch releases.
+</Note>
+
+AI Gateway supports durable text batches through `experimental_startTextBatch`, `experimental_getBatchStatus`, and `experimental_getBatchResults`. See the [AI Gateway batch processing guide](https://vercel.com/docs/ai-gateway/models-and-providers/batch-processing) for supported models, limits, and the complete lifecycle.
+
+Pass a publicly reachable HTTPS `webhookUrl` when starting a batch to receive a terminal notification instead of polling. AI Gateway sends `batch.completed`, `batch.failed`, or `batch.cancelled`. The event contains terminal status information but not batch results. Completion webhooks are an AI Gateway capability; direct Anthropic and OpenAI batch providers return an unsupported warning when this option is provided.
+
+```ts filename="start-batch.ts"
+import { randomUUID } from 'node:crypto';
+import {
+  experimental_startTextBatch as startTextBatch,
+  type Experimental_TextBatchReference as TextBatchReference,
+  type GatewayProviderMetadata,
+} from 'ai';
+
+// The receiver uses this token to look up the expected batch and signing
+// secret before trusting anything in the webhook body.
+const token = randomUUID();
+const model = 'anthropic/claude-haiku-4.5' as const;
+
+// Reserve the token before starting so an early delivery finds a retryable
+// pending record rather than an unknown callback.
+await reserveBatchWebhook(token);
+
+const batch = await startTextBatch({
+  model,
+  requests: [
+    { id: 'france', prompt: 'What is the capital of France?' },
+    { id: 'germany', prompt: 'What is the capital of Germany?' },
+  ],
+  providerOptions: {
+    gateway: { idempotencyKey: token },
+  },
+  webhookUrl: `https://example.com/api/batch-webhook?token=${token}`,
+});
+
+const gatewayMetadata = batch.providerMetadata?.gateway as
+  | GatewayProviderMetadata
+  | undefined;
+const signingSecret = gatewayMetadata?.asyncJob?.webhookSigningSecret;
+
+if (typeof signingSecret !== 'string') {
+  throw new Error('AI Gateway did not return a webhook signing secret.');
+}
+
+// Keep sensitive provider metadata out of the receiver queue and logs.
+const batchReference = {
+  version: batch.version,
+  type: batch.type,
+  id: batch.id,
+  provider: batch.provider,
+  modelId: batch.modelId,
+} satisfies TextBatchReference;
+
+await completeBatchWebhookReservation(token, {
+  batch: batchReference,
+  model,
+  signingSecret,
+});
+```
+
+The signing secret is returned only in the start response. Reserve the callback token before submitting the batch, then persist the secret, model, and minimal `batch` reference before the process exits. The stable `providerOptions.gateway.idempotencyKey` makes retrying an ambiguous start safe. Reuse the reserved token when retrying; do not generate a new one. Delete the reservation after a definitive start failure. While the reservation is still pending, the receiver should return a retryable response so an early delivery is sent again after setup completes.
+
+The receiver must verify the `x-ai-gateway-signature` header against a bounded raw request body before trusting the event:
+
+```ts filename="app/api/batch-webhook/route.ts"
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+const MAX_AGE_SECONDS = 5 * 60;
+const MAX_BODY_BYTES = 64 * 1024;
+
+export async function POST(request: Request) {
+  const token = new URL(request.url).searchParams.get('token');
+  if (token == null) return new Response(null, { status: 401 });
+
+  const record = await loadBatchWebhook(token);
+  if (record == null) return new Response(null, { status: 401 });
+  if (record.state !== 'ready') return new Response(null, { status: 503 });
+
+  const declaredLength = request.headers.get('content-length');
+  if (declaredLength != null && Number(declaredLength) > MAX_BODY_BYTES) {
+    return new Response(null, { status: 413 });
+  }
+
+  const rawBody = await readBodyWithLimit(request, MAX_BODY_BYTES);
+  if (rawBody == null) return new Response(null, { status: 413 });
+
+  const signature = request.headers.get('x-ai-gateway-signature');
+  if (
+    signature == null ||
+    !verifySignature({
+      header: signature,
+      rawBody,
+      secret: record.signingSecret,
+    })
+  ) {
+    return new Response(null, { status: 401 });
+  }
+
+  let event: { data?: { jobId?: string; status?: string } };
+  try {
+    event = JSON.parse(rawBody);
+  } catch {
+    return new Response(null, { status: 400 });
+  }
+
+  const jobId = event.data?.jobId;
+  const status = event.data?.status;
+  if (
+    jobId !== record.batch.id ||
+    (status !== 'cancelled' && status !== 'completed' && status !== 'failed')
+  ) {
+    return new Response(null, { status: 401 });
+  }
+
+  // The header is not signed, so require it to match the signed event body.
+  const deliveryId = `${jobId}-${status}`;
+  if (request.headers.get('x-ai-gateway-idempotency-key') !== deliveryId) {
+    return new Response(null, { status: 401 });
+  }
+
+  await enqueueBatchResultFetch({
+    batch: record.batch,
+    deliveryId,
+    model: record.model,
+  });
+
+  return new Response(null, { status: 204 });
+}
+
+async function readBodyWithLimit(request: Request, maxBytes: number) {
+  if (request.body == null) return '';
+
+  const reader = request.body.getReader();
+  const decoder = new TextDecoder();
+  let body = '';
+  let size = 0;
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) return body + decoder.decode();
+
+      size += value.byteLength;
+      if (size > maxBytes) {
+        await reader.cancel();
+        return undefined;
+      }
+
+      body += decoder.decode(value, { stream: true });
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function verifySignature({
+  header,
+  rawBody,
+  secret,
+}: {
+  header: string;
+  rawBody: string;
+  secret: string;
+}) {
+  const timestamp = header.match(/(?:^|,)t=(\d+)/)?.[1];
+  const digest = header.match(/(?:^|,)v1=([0-9a-f]{64})(?:,|$)/)?.[1];
+  if (timestamp == null || digest == null) return false;
+
+  const expected = createHmac('sha256', secret)
+    .update(`${timestamp}.${rawBody}`, 'utf8')
+    .digest('hex');
+  const provided = Buffer.from(digest, 'hex');
+  const computed = Buffer.from(expected, 'hex');
+  if (provided.length !== computed.length) return false;
+  if (!timingSafeEqual(provided, computed)) return false;
+
+  return Math.abs(Date.now() / 1000 - Number(timestamp)) <= MAX_AGE_SECONDS;
+}
+```
+
+The signature header has the form `t=<unix seconds>,v1=<hex digest>`, where `v1` is the HMAC-SHA256 digest of `"<t>.<raw body>"`. Verify a size-limited raw request body rather than a re-serialized object, use a timing-safe comparison, reject stale timestamps, and reject events whose `data.jobId` does not match the persisted `batch.id`.
+
+AI Gateway expects a 2xx response within 10 seconds and retries failed deliveries. It does not follow redirects, so the callback endpoint itself must return the 2xx response. Retries carry the same `x-ai-gateway-idempotency-key` value (`<jobId>-<status>`), which receivers can use for deduplication. After verification, pass the persisted model and `batch` reference to `experimental_getBatchStatus` and `experimental_getBatchResults`. Delivery is best-effort, so periodically reconcile persisted batches by status as a fallback for a notification that exhausts its retries.
+
 ## Reranking Models
 
 You can create reranking models using the `rerankingModel` method on the provider instance:
@@ -829,9 +1023,9 @@ The Tako Search tool supports these optional configuration options:
   - **includeContents** _boolean_ - Inline each page's extracted full text in `content`. **articleContentMaxChars** caps it, defaulting to 30,000 characters (maximum 1,000,000).
 - **sources.data** _object_ - Configure data results:
   - **count** _number_ - Maximum data results, 1-20. Defaults to 5.
-  - **includeContents** _boolean_ - Inline each card's underlying rows in `content.dataset` as typed, unit-labeled columns.
+  - **includeContents** _boolean_ - Inline each card's underlying rows in `content.dataset` as typed, unit-labeled columns. This adds a data surcharge based on the row count and dataset source. To estimate cost, first search with `includeContents: false` and inspect `cards.content.export_pricing`. Because this applies to every returned card, use `count` and `maxRows` to control cost.
   - **contentFormat** _'json_compact' | 'json_records' | 'csv' | 'card_json'_ - Serialization for inlined card data. Defaults to `'json_compact'`.
-  - **maxRows** _number_ - Row cap for inlined card data. Omit to use your account's default inline cap (20 rows on the standard plan); maximum 2,000.
+  - **maxRows** _number_ - Row cap per result. Omit to use the allowance in `cards.content.export_pricing`. A data surcharge applies per 1,000 exported rows; lower values reduce cost.
   - **nodeIds** _string[]_ - Data Graph node IDs to prioritize. Up to 20.
   - **strict** _boolean_ - Only return cards matching `nodeIds`. Requires at least one `nodeIds` value.
 - **location** _object_ - End-user `{ latitude, longitude }` coordinates for localized results.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-sdk/gateway",
   "private": false,
-  "version": "4.0.63",
+  "version": "4.0.67",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -30,18 +30,18 @@
     }
   },
   "dependencies": {
-    "@vercel/oidc": "3.2.0",
-    "@ai-sdk/provider": "4.0.7",
-    "@ai-sdk/provider-utils": "5.0.29"
+    "@ai-sdk/provider": "4.0.8",
+    "@ai-sdk/provider-utils": "5.0.32",
+    "@vercel/oidc": "3.2.0"
   },
   "devDependencies": {
+    "@ai-sdk/test-server": "2.0.1",
     "@types/node": "22.19.19",
+    "@vercel/ai-tsconfig": "0.0.0",
     "tsup": "^8.5.1",
     "tsx": "4.23.12",
     "typescript": "5.8.3",
-    "zod": "3.25.76",
-    "@ai-sdk/test-server": "2.0.1",
-    "@vercel/ai-tsconfig": "0.0.0"
+    "zod": "3.25.76"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"

package/src/gateway-language-model-batch.ts

@@ -1,5 +1,4 @@
 import {
-  APICallError,
   type Experimental_BatchLanguageModelV4 as BatchLanguageModelV4,
   type Experimental_BatchV4ItemResult as BatchV4ItemResult,
   type Experimental_BatchV4OperationOptions as BatchV4OperationOptions,
@@ -15,9 +14,10 @@ import {
   combineHeaders,
   convertAsyncIteratorToReadableStream,
   createJsonErrorResponseHandler,
+  createJsonLinesResponseHandler,
   createJsonResponseHandler,
   getErrorMessage,
-  parseJSON,
+  normalizeBatchRequestCounts,
   postJsonToApi,
   resolve,
   WORKFLOW_SERIALIZE,
@@ -63,6 +63,7 @@ export class GatewayBatchLanguageModel
     providerOptions,
     headers,
     abortSignal,
+    webhookUrl,
   }: BatchV4StartOptions<LanguageModelV4BatchRequest>): Promise<BatchV4StartResult> {
     const resolvedHeaders = this.config.headers
       ? await resolve(this.config.headers)
@@ -84,6 +85,7 @@ export class GatewayBatchLanguageModel
             : undefined,
         ),
         body: {
+          ...(webhookUrl != null && { callbackUrl: webhookUrl }),
           modelId: this.modelId,
           requests: requests.map(request => ({
             id: request.id,
@@ -188,7 +190,7 @@ export class GatewayBatchLanguageModel
       : undefined;
 
     try {
-      const { value: stream } = await postJsonToApi({
+      const { value: lines } = await postJsonToApi({
         url: this.getBatchUrl('results'),
         headers: combineHeaders(
           resolvedHeaders,
@@ -197,28 +199,9 @@ export class GatewayBatchLanguageModel
           await resolve(this.config.o11yHeaders),
         ),
         body: { batchId },
-        successfulResponseHandler: async ({
-          response,
-          url,
-          requestBodyValues,
-        }: {
-          url: string;
-          requestBodyValues: unknown;
-          response: Response;
-        }) => {
-          if (response.body == null) {
-            throw new APICallError({
-              message: 'Batch results response body is empty',
-              url,
-              requestBodyValues,
-              statusCode: response.status,
-            });
-          }
-          return {
-            value: response.body,
-            responseHeaders: Object.fromEntries([...response.headers]),
-          };
-        },
+        successfulResponseHandler: createJsonLinesResponseHandler(
+          gatewayBatchItemResultLineSchema,
+        ),
         failedResponseHandler: createJsonErrorResponseHandler({
           errorSchema: z.any(),
           errorToMessage: data => getErrorMessage(data) ?? 'unknown error',
@@ -228,7 +211,7 @@ export class GatewayBatchLanguageModel
       });
 
       return convertAsyncIteratorToReadableStream(
-        parseGatewayBatchResultLines(stream),
+        convertGatewayBatchResultLines(lines),
       );
     } catch (error) {
       if (isAbortOrTimeoutError(error)) {
@@ -340,7 +323,12 @@ function convertGatewayBatchStatus(body: {
   expiresAt?: string | null;
   providerMetadata?: Record<string, Record<string, unknown>> | null;
 }): BatchV4Status {
-  const requestCounts = convertGatewayBatchRequestCounts(body.requestCounts);
+  const requestCounts = normalizeBatchRequestCounts({
+    total: body.requestCounts?.total,
+    pending: body.requestCounts?.pending,
+    completed: body.requestCounts?.completed,
+    failed: body.requestCounts?.failed,
+  });
 
   return {
     status: body.status,
@@ -365,112 +353,27 @@ function convertGatewayBatchStatus(body: {
 }
 
 /**
- * The spec's `requestCounts` requires all four counters; the Gateway's
- * persisted descriptor allows partial counts. Only forward counts when the
- * full set is present rather than fabricating zeros.
- */
-function convertGatewayBatchRequestCounts(
-  counts:
-    | {
-        total?: number | null;
-        pending?: number | null;
-        completed?: number | null;
-        failed?: number | null;
-      }
-    | null
-    | undefined,
-): BatchV4Status['requestCounts'] | undefined {
-  if (
-    counts == null ||
-    typeof counts.total !== 'number' ||
-    typeof counts.pending !== 'number' ||
-    typeof counts.completed !== 'number' ||
-    typeof counts.failed !== 'number'
-  ) {
-    return undefined;
-  }
-
-  return {
-    total: counts.total,
-    pending: counts.pending,
-    completed: counts.completed,
-    failed: counts.failed,
-  };
-}
-
-/**
- * Incremental NDJSON line splitter for the batch results stream: buffers
- * partial lines across chunks and flushes a trailing line without a final
- * newline. Each non-empty line is one `BatchV4ItemResult` JSON object.
+ * Converts the minimally validated Gateway batch result lines. The Gateway
+ * already sanitizes the complete result objects server-side.
  *
- * @param stream - The raw NDJSON byte stream from the batch results route.
- * @yields One minimally-validated `BatchV4ItemResult` per non-empty line.
+ * @yields Each Gateway batch item result.
  */
-async function* parseGatewayBatchResultLines(
-  stream: ReadableStream<Uint8Array>,
+async function* convertGatewayBatchResultLines(
+  lines: AsyncIterable<unknown>,
 ): AsyncGenerator<BatchV4ItemResult<LanguageModelV4GenerateResult>> {
-  const reader = stream.getReader();
-  const decoder = new TextDecoder();
-  let buffer = '';
-  let finished = false;
-
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-
-      if (done) {
-        finished = true;
-        buffer += decoder.decode();
-        break;
-      }
-
-      buffer += decoder.decode(value, { stream: true });
-
-      let lineEnd = buffer.indexOf('\n');
-      while (lineEnd !== -1) {
-        const line = buffer.slice(0, lineEnd).replace(/\r$/, '');
-        buffer = buffer.slice(lineEnd + 1);
-
-        if (line.trim().length > 0) {
-          yield await parseGatewayBatchResultLine(line);
-        }
-
-        lineEnd = buffer.indexOf('\n');
+  for await (const line of lines) {
+    const item = line as BatchV4ItemResult<LanguageModelV4GenerateResult>;
+
+    // JSON carries `response.timestamp` as an ISO string; core expects a Date.
+    if (item.status === 'succeeded') {
+      const response = item.result?.response;
+      if (response !== undefined && typeof response.timestamp === 'string') {
+        response.timestamp = new Date(response.timestamp);
       }
     }
 
-    const finalLine = buffer.replace(/\r$/, '');
-    if (finalLine.trim().length > 0) {
-      yield await parseGatewayBatchResultLine(finalLine);
-    }
-  } finally {
-    if (!finished) {
-      await reader.cancel().catch(() => {});
-    }
-    reader.releaseLock();
-  }
-}
-
-async function parseGatewayBatchResultLine(
-  line: string,
-): Promise<BatchV4ItemResult<LanguageModelV4GenerateResult>> {
-  // Minimal validation (id + status); items pass through otherwise — the
-  // Gateway already sanitizes them server-side.
-  const parsed = await parseJSON({
-    text: line,
-    schema: gatewayBatchItemResultLineSchema,
-  });
-  const item =
-    parsed as unknown as BatchV4ItemResult<LanguageModelV4GenerateResult>;
-  // JSON carries `response.timestamp` as an ISO string; core expects a Date
-  // (`GeneratedFile`-style consumers call `.toISOString()`).
-  if (item.status === 'succeeded') {
-    const response = item.result?.response;
-    if (response !== undefined && typeof response.timestamp === 'string') {
-      response.timestamp = new Date(response.timestamp);
-    }
+    yield item;
   }
-  return item;
 }
 
 const gatewayBatchItemResultLineSchema = z

package/src/gateway-language-model-settings.ts

@@ -47,7 +47,6 @@ export type GatewayModelId =
   | 'anthropic/claude-sonnet-4.6'
   | 'anthropic/claude-sonnet-5'
   | 'arcee-ai/trinity-large-thinking'
-  | 'arcee-ai/trinity-mini'
   | 'bytedance/seed-1.6'
   | 'bytedance/seed-1.8'
   | 'cohere/command-a'
@@ -103,13 +102,13 @@ export type GatewayModelId =
   | 'minimax/minimax-m2.5'
   | 'minimax/minimax-m2.5-highspeed'
   | 'minimax/minimax-m2.7'
+  | 'minimax/minimax-m2.7-free'
   | 'minimax/minimax-m2.7-highspeed'
   | 'minimax/minimax-m3'
+  | 'minimax/minimax-m3-free'
   | 'mistral/codestral'
   | 'mistral/devstral-2'
   | 'mistral/devstral-small-2'
-  | 'mistral/magistral-medium'
-  | 'mistral/magistral-small'
   | 'mistral/ministral-14b'
   | 'mistral/ministral-3b'
   | 'mistral/ministral-8b'
@@ -133,7 +132,6 @@ export type GatewayModelId =
   | 'nvidia/nemotron-3-super-120b-a12b'
   | 'nvidia/nemotron-3-ultra-550b-a55b'
   | 'nvidia/nemotron-3.5-lightning'
-  | 'nvidia/nemotron-3.5-lightning-free'
   | 'nvidia/nemotron-nano-12b-v2-vl'
   | 'nvidia/nemotron-nano-9b-v2'
   | 'openai/gpt-3.5-turbo'
@@ -148,7 +146,6 @@ export type GatewayModelId =
   | 'openai/gpt-4o-fast'
   | 'openai/gpt-4o-mini'
   | 'openai/gpt-4o-mini-fast'
-  | 'openai/gpt-4o-mini-search-preview'
   | 'openai/gpt-5'
   | 'openai/gpt-5-codex'
   | 'openai/gpt-5-fast'
@@ -184,10 +181,10 @@ export type GatewayModelId =
   | 'openai/gpt-5.6-terra-fast'
   | 'openai/gpt-oss-120b'
   | 'openai/gpt-oss-20b'
+  | 'openai/gpt-oss-safeguard-120b'
   | 'openai/gpt-oss-safeguard-20b'
   | 'openai/o1'
   | 'openai/o3'
-  | 'openai/o3-deep-research'
   | 'openai/o3-fast'
   | 'openai/o3-mini'
   | 'openai/o3-pro'
@@ -235,5 +232,6 @@ export type GatewayModelId =
   | 'zai/glm-5.2'
   | 'zai/glm-5.2-fast'
   | 'zai/glm-5.3'
+  | 'zai/glm-5.3-flash'
   | 'zai/glm-5v-turbo'
   | (string & {});

package/src/gateway-provider-metadata.ts

@@ -0,0 +1,27 @@
+import type { JSONValue } from '@ai-sdk/provider';
+
+/**
+ * Metadata for an asynchronous AI Gateway job.
+ */
+export type GatewayAsyncJobMetadata = {
+  readonly jobId: string;
+  readonly status: string;
+
+  /**
+   * Secret for verifying customer webhook deliveries. This is sensitive,
+   * start-response-only metadata and must not be logged or forwarded.
+   */
+  readonly webhookSigningSecret?: string;
+  readonly [key: string]: JSONValue | undefined;
+};
+
+/**
+ * Shape of the inner `providerMetadata.gateway` object returned by AI Gateway
+ * operations.
+ *
+ * Additional fields may be added without a package update.
+ */
+export type GatewayProviderMetadata = {
+  readonly asyncJob?: GatewayAsyncJobMetadata;
+  readonly [key: string]: JSONValue | undefined;
+};

package/src/gateway-video-model-settings.ts

@@ -7,6 +7,7 @@ export type GatewayVideoModelId =
   | 'alibaba/wan-v2.6-t2v'
   | 'alibaba/wan-v2.7-r2v'
   | 'alibaba/wan-v2.7-t2v'
+  | 'alibaba/wan-v3.0-video'
   | 'bfl/flux-3-video'
   | 'bytedance/seedance-2.0'
   | 'bytedance/seedance-2.0-fast'

package/src/index.ts

@@ -41,6 +41,10 @@ export type {
   GatewayProvider,
   GatewayProviderSettings,
 } from './gateway-provider';
+export type {
+  GatewayAsyncJobMetadata,
+  GatewayProviderMetadata,
+} from './gateway-provider-metadata';
 export type {
   GatewayProviderOptions,
   /** @deprecated Use `GatewayProviderOptions` instead. */

package/src/tool/tako-search.ts

@@ -14,15 +14,28 @@ export type TakoContentFormat =
   | 'json_records';
 
 export interface TakoDataSourceConfig {
-  /** Maximum number of data cards to return (1-20). */
+  /**
+   * Maximum number of data results to return (1-20). When includeContents is
+   * true, each additional result adds its own data surcharge.
+   */
   count?: number;
-  /** Inline underlying card data in the response. This can add a data charge. */
+  /**
+   * Inline rows for each data result. This adds a data surcharge based on row
+   * count and dataset source. To estimate cost, search with includeContents
+   * disabled and inspect cards.content.export_pricing. This applies to every
+   * returned card; limit sources.data.count and sources.data.maxRows to control
+   * cost.
+   */
   includeContents?: boolean;
   /** Requested delivery mode for card data. Search cards are always inlined. */
   mode?: 'inline' | 'url';
   /** Serialization for inlined card data. */
   contentFormat?: TakoContentFormat;
-  /** Maximum rows for inlined card data. The service clamps large values. */
+  /**
+   * Maximum rows to inline per result. Omit to use the allowance in
+   * cards.content.export_pricing. A data surcharge applies per 1,000 exported
+   * rows; lower values reduce cost.
+   */
   maxRows?: number;
   /** Data Graph node IDs to prioritize. */
   nodeIds?: string[];
@@ -190,7 +203,6 @@ export interface TakoCard {
   relevance?: 'High' | 'Low' | 'Medium' | null;
   content?: TakoResultContent | null;
   exportable?: boolean;
-  relevance_score?: number | null;
   nodes?: Array<{
     id: string;
     type: 'entity' | 'metric';
@@ -215,7 +227,6 @@ export interface TakoWebResult {
   source_name?: string | null;
   publish_date?: string | null;
   content?: TakoResultContent | null;
-  citation_number?: number | null;
 }
 
 export interface TakoSearchResponse {
@@ -254,11 +265,15 @@ const takoDataSourceInputSchema = z.object({
   count: z
     .number()
     .optional()
-    .describe('Maximum number of data cards to return (1-20).'),
+    .describe(
+      'Maximum number of data results to return (1-20). When include_contents is true, each additional result adds its own data surcharge.',
+    ),
   include_contents: z
     .boolean()
     .optional()
-    .describe('Inline underlying card data. This can add a data charge.'),
+    .describe(
+      'Inline rows for each data result. This adds a data surcharge based on row count and dataset source. To estimate cost, search with include_contents disabled and inspect cards.content.export_pricing. This applies to every returned card; limit sources.data.count and sources.data.max_rows to control cost.',
+    ),
   mode: z
     .enum(['inline', 'url'])
     .optional()
@@ -272,7 +287,9 @@ const takoDataSourceInputSchema = z.object({
   max_rows: z
     .number()
     .optional()
-    .describe('Maximum rows for inlined card data.'),
+    .describe(
+      'Maximum rows to inline per result. Omit to use the allowance in cards.content.export_pricing. A data surcharge applies per 1,000 exported rows; lower values reduce cost.',
+    ),
   node_ids: z
     .array(z.string())
     .optional()
@@ -493,7 +510,6 @@ const takoCardSchema = z
     relevance: z.enum(['High', 'Low', 'Medium']).nullish(),
     content: takoResultContentSchema.nullish(),
     exportable: z.boolean().optional(),
-    relevance_score: z.number().nullish(),
     nodes: z
       .array(
         z.object({
@@ -525,7 +541,6 @@ const takoWebResultSchema = z
     source_name: z.string().nullish(),
     publish_date: z.string().nullish(),
     content: takoResultContentSchema.nullish(),
-    citation_number: z.number().nullish(),
   })
   .passthrough();