experimental_startBatch

Starts an asynchronous batch of text or image generation requests. For a complete guide to the batch lifecycle, see Batch.

import { experimental_startBatch as startBatch } from 'ai';

const batch = await startBatch({
  requests: [
    {
      id: 'france',
      type: 'text',
      model: 'gpt-5.4-nano',
      prompt: 'What is the capital of France?',
    },
  ],
});

Import

import { experimental_startBatch } from "ai"

API Signature

Parameters

• provider? (Experimental_BatchProvider): The provider to use. Defaults to the global provider, or the AI Gateway when no global provider is configured.
• requests (Array<Experimental_BatchRequest>): The independent requests to process. Each request must have a unique, non-empty id, a supported type, and type-specific properties such as model and prompt or messages for text requests.
• providerOptions? (ProviderOptions): Additional provider-specific options for the batch.
• webhookUrl? (string): URL to notify when the batch reaches a terminal state. Support and payloads are provider-specific.
• abortSignal? (AbortSignal): An optional abort signal to cancel the request that starts the batch.
• timeout? (number | { totalMs?: number }): Maximum time allowed for the batch creation request.
• headers? (Record<string, string | undefined>): Additional HTTP headers for the request.

Returns

• version (2): Version of the serializable batch reference.
• id (string): Provider batch identifier.
• provider (string): Provider identifier for the batch.
• status ('pending' | 'completed' | 'failed'): Initial normalized batch status.
• rawStatus? (string): The provider-specific batch status, when available.
• requestCounts? ({ total: number; pending: number; completed: number; failed: number }): Provider-reported request counts.
• error? (Experimental_BatchError): Error details when the batch fails.
• createdAt? (string): Creation timestamp, when provided by the provider.
• expiresAt? (string): Expiration timestamp, when provided by the provider.
• providerMetadata? (ProviderMetadata): Provider-specific metadata for the batch.
• warnings (Warning[]): Warnings returned while starting the batch.