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.

POST /batch-predictions

Python

Python

import os
from datagrid_ai import Datagrid

client = Datagrid(
    api_key=os.environ.get("DATAGRID_API_KEY"),  # This is the default and can be omitted
)
batch_prediction = client.batch_predictions.create(
    items=[{
        "custom_id": "drawing_001",
        "file_id": "file_abc123",
        "page": 1,
    }, {
        "custom_id": "drawing_002",
        "file_id": "file_def456",
    }],
    model="gemini-2.5-flash",
    output_schema={
        "type": "object",
        "additionalProperties": False,
        "properties": {
            "project_name": {
                "type": "string"
            },
            "sheet_title": {
                "type": "string"
            },
            "revision": {
                "type": "string"
            },
        },
        "required": ["project_name", "sheet_title"],
    },
    prompt="Extract the project name, sheet title, and revision from this drawing.",
    completion_window="24h",
    metadata={
        "project": "alpha"
    },
)
print(batch_prediction.id)

201

{
  "object": "batch_prediction",
  "id": "bpred_abc123",
  "status": "completed",
  "model": "gemini-2.5-flash",
  "completion_window": "24h",
  "created_at": "2026-04-10T12:00:00.000Z",
  "expires_at": "2026-04-11T12:00:00.000Z",
  "in_progress_at": "2026-04-10T12:01:00.000Z",
  "finalizing_at": "2026-04-10T12:05:00.000Z",
  "completed_at": "2026-04-10T12:06:00.000Z",
  "failed_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "expired_at": null,
  "request_counts": {
    "total": 2,
    "processing": 0,
    "succeeded": 2,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "metadata": {
    "project": "alpha"
  },
  "error": null,
  "results_url": "/v1/batch-predictions/bpred_abc123/results"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key · string

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

application/json

model · enum<string> · required

LLM model to use for every item in the batch.

Available options: gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.5-pro, anthropic.claude-haiku-4-5-20251001-v1:0, anthropic.claude-sonnet-4-5-20250929-v1:0, amazon.nova-2-lite-v1:0

items · object[] · required

Files to process. Each item uses the shared prompt and output_schema.

Required array length: 1 - 5000 elements

Show child attributes

prompt · string · required

Shared instruction applied to each item in the batch.

Minimum string length: 1

output_schema · object · required

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

completion_window · enum<string> | null

Requested completion window. Defaults to 24h when omitted; no other values are currently supported.

Available options: 24h

metadata · object

Optional metadata map with up to 16 entries. Metadata keys must be 64 characters or fewer and values must be 512 characters or fewer.

Show child attributes

Response

201

application/json

Batch prediction created

The batch_prediction object represents an asynchronous batch prediction job.

object · enum<string> · required

The object type, which is always batch_prediction.

Available options: batch_prediction

id · string · required

The id of the batch prediction.

status · enum<string> · required

Current batch lifecycle state. Terminal states are completed, failed, expired, and cancelled.

Available options: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled

model · enum<string> · required

LLM model to use for every item in the batch.

Available options: gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.5-pro, anthropic.claude-haiku-4-5-20251001-v1:0, anthropic.claude-sonnet-4-5-20250929-v1:0, amazon.nova-2-lite-v1:0

completion_window · enum<string> · required

Requested completion window.

Available options: 24h

created_at · string<date-time> · required

ISO timestamp when the batch was created.

expires_at · string<date-time> · required

ISO timestamp when the batch completion window expires.

in_progress_at · string<date-time> | null · required

ISO timestamp when the batch entered in_progress, or null if it has not.

finalizing_at · string<date-time> | null · required

ISO timestamp when the batch entered finalizing, or null if it has not.

completed_at · string<date-time> | null · required

ISO timestamp when the batch reached completed, or null otherwise.

failed_at · string<date-time> | null · required

ISO timestamp when the batch reached failed, or null otherwise.

cancelling_at · string<date-time> | null · required

ISO timestamp when cancellation was requested, or null otherwise.

cancelled_at · string<date-time> | null · required

ISO timestamp when the batch reached cancelled, or null otherwise.

expired_at · string<date-time> | null · required

ISO timestamp when the batch reached expired, or null otherwise.

request_counts · object · required

The sum of processing, succeeded, errored, canceled, and expired equals total.

Show child attributes

metadata · object · required

Optional metadata map with up to 16 entries. Metadata keys must be 64 characters or fewer and values must be 512 characters or fewer.

Show child attributes

error · object · required

Batch-level terminal error details for failed, cancelled, or expired batches; otherwise null.

Show child attributes

results_url · string<uri-reference> | null · required

Relative URL for the NDJSON results stream once the batch is terminal. This becomes null after retained result lines are cleaned up.