Create batch prediction
Create a new asynchronous batch prediction job. The response returns immediately with a validating batch while Datagrid validates files and starts background processing. Supply an Idempotency-Key header to safely retry the same create request. The requested model must be available for the authenticated teamspace cloud provider.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Optional idempotency key. Reusing the same key with the same request body replays the original batch. Reusing it with a different request body returns 409 Conflict. Cached results expire after 24 hours.
Body
LLM model to use for every item in the batch. Model availability is cloud-aware: AWS teamspaces accept Bedrock-native batch-capable models, while GCP teamspaces accept non-Bedrock batch-capable models and reject Bedrock-only ids. Deprecated gemini-2.0-flash is accepted for backward compatibility and automatically runs as gemini-3.1-flash-lite.
gemini-2.0-flash, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-3.1-flash-lite, gemini-3.5-flash, gemini-2.5-pro, gemini-3.1-pro-preview, gpt-4o, gpt-4o-mini, gpt-4.1-mini, gpt-4.1, gpt-5-mini, gpt-5, gpt-5.1, claude-sonnet-4@20250514, claude-opus-4-1@20250805, claude-haiku-4-5@20251001, claude-sonnet-4-5@20250929, claude-sonnet-4-6@default, claude-opus-4-5@20251101, claude-opus-4-6@default, claude-opus-4-7, claude-opus-4-8, anthropic.claude-haiku-4-5-20251001-v1:0, anthropic.claude-sonnet-4-5-20250929-v1:0, anthropic.claude-sonnet-4-6, anthropic.claude-opus-4-5-20251101-v1:0, anthropic.claude-opus-4-6-v1, anthropic.claude-opus-4-7, anthropic.claude-opus-4-8, amazon.nova-2-lite-v1:0 Files to process. Each item uses the shared prompt and output_schema.
1 - 5000 elementsShared instruction applied to each item in the batch.
1JSON Schema Draft 2020-12 describing each item output. The root schema must be type: object. The batch prediction API currently rejects $defs, $ref, allOf, anyOf, not, oneOf, and patternProperties anywhere in the schema.
Requested completion window. Defaults to 24h when omitted; no other values are currently supported.
24h Optional metadata map with up to 16 entries. Metadata keys must be 64 characters or fewer and values must be 512 characters or fewer.
Response
Batch prediction created
The batch_prediction object represents an asynchronous batch prediction job.
The object type, which is always batch_prediction.
batch_prediction The id of the batch prediction.
Current batch lifecycle state. Terminal states are completed, failed, expired, and cancelled.
validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled LLM model to use for every item in the batch. Model availability is cloud-aware: AWS teamspaces accept Bedrock-native batch-capable models, while GCP teamspaces accept non-Bedrock batch-capable models and reject Bedrock-only ids. Deprecated gemini-2.0-flash is accepted for backward compatibility and automatically runs as gemini-3.1-flash-lite.
gemini-2.0-flash, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-3.1-flash-lite, gemini-3.5-flash, gemini-2.5-pro, gemini-3.1-pro-preview, gpt-4o, gpt-4o-mini, gpt-4.1-mini, gpt-4.1, gpt-5-mini, gpt-5, gpt-5.1, claude-sonnet-4@20250514, claude-opus-4-1@20250805, claude-haiku-4-5@20251001, claude-sonnet-4-5@20250929, claude-sonnet-4-6@default, claude-opus-4-5@20251101, claude-opus-4-6@default, claude-opus-4-7, claude-opus-4-8, anthropic.claude-haiku-4-5-20251001-v1:0, anthropic.claude-sonnet-4-5-20250929-v1:0, anthropic.claude-sonnet-4-6, anthropic.claude-opus-4-5-20251101-v1:0, anthropic.claude-opus-4-6-v1, anthropic.claude-opus-4-7, anthropic.claude-opus-4-8, amazon.nova-2-lite-v1:0 Requested completion window.
24h ISO timestamp when the batch was created.
ISO timestamp when the batch completion window expires.
ISO timestamp when the batch entered in_progress, or null if it has not.
ISO timestamp when the batch entered finalizing, or null if it has not.
ISO timestamp when the batch reached completed, or null otherwise.
ISO timestamp when the batch reached failed, or null otherwise.
ISO timestamp when cancellation was requested, or null otherwise.
ISO timestamp when the batch reached cancelled, or null otherwise.
ISO timestamp when the batch reached expired, or null otherwise.
The sum of processing, succeeded, errored, canceled, and expired equals total.
Optional metadata map with up to 16 entries. Metadata keys must be 64 characters or fewer and values must be 512 characters or fewer.
Batch-level terminal error details for failed, cancelled, or expired batches; otherwise null.
Relative URL for the NDJSON results stream once the batch is terminal. This becomes null after retained result lines are cleaned up.