AI SDK
ReferenceAI SDK Core

experimental_startBatch

API Reference for experimental_startBatch.

Batch support is experimental and the API may change in patch releases.

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.

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.
PreviouspipeAgentUIStreamToResponseNexttool