> ## Documentation Index > Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml post /batch-predictions openapi: 3.0.3 info: version: 0.1.1 title: Datagrid API description: Datagrid API servers: - url: https://api.datagrid.com/v1 security: - BearerAuth: [] paths: /batch-predictions: post: tags: - Batch Predictions summary: Create batch prediction description: >- 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. operationId: BatchPredictions.createBatchPrediction parameters: - name: Idempotency-Key in: header required: false description: >- 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. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchPredictionCreateRequest' example: model: gemini-2.5-flash prompt: >- Extract the project name, sheet title, and revision from this drawing. output_schema: type: object additionalProperties: false properties: project_name: type: string sheet_title: type: string revision: type: string required: - project_name - sheet_title items: - custom_id: drawing_001 file_id: file_abc123 page: 1 - custom_id: drawing_002 file_id: file_def456 completion_window: 24h metadata: project: alpha responses: '201': description: Batch prediction created headers: Location: description: Canonical URI for the created batch prediction. schema: type: string X-Request-Id: description: Request identifier for tracing and support. schema: type: string content: application/json: schema: $ref: '#/components/schemas/BatchPrediction' '401': description: >- Unauthorized. Authentication is required to create a batch prediction. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '403': description: >- Forbidden. The teamspace does not have enough credits to enqueue batch prediction work. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '409': description: >- Conflict. The supplied `Idempotency-Key` was already used with a different request body. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '422': description: Validation failed. The request body is invalid. content: application/problem+json: schema: $ref: '#/components/schemas/ValidationProblemDetails' '429': description: >- Rate limit exceeded. The request has been throttled or admission control rejected the batch. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' x-codeSamples: - lang: JavaScript source: |- import Datagrid from 'datagrid-ai'; const client = new Datagrid({ apiKey: process.env['DATAGRID_API_KEY'], // This is the default and can be omitted }); const batchPrediction = await client.batchPredictions.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' }, }); console.log(batchPrediction.id); - lang: Python source: |- 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) components: schemas: BatchPredictionCreateRequest: type: object required: - model - items - prompt - output_schema properties: model: $ref: '#/components/schemas/BatchPredictionModel' items: type: array description: >- Files to process. Each item uses the shared `prompt` and `output_schema`. minItems: 1 maxItems: 5000 items: $ref: '#/components/schemas/BatchPredictionItemInput' prompt: type: string minLength: 1 description: Shared instruction applied to each item in the batch. output_schema: type: object description: >- 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. additionalProperties: true completion_window: type: string enum: - 24h description: >- Requested completion window. Defaults to `24h` when omitted; no other values are currently supported. nullable: true metadata: $ref: '#/components/schemas/Metadata' BatchPrediction: type: object description: >- The `batch_prediction` object represents an asynchronous batch prediction job. required: - object - id - status - model - completion_window - created_at - expires_at - in_progress_at - finalizing_at - completed_at - failed_at - cancelling_at - cancelled_at - expired_at - request_counts - metadata - error - results_url properties: object: type: string enum: - batch_prediction description: The object type, which is always `batch_prediction`. id: type: string description: The id of the batch prediction. status: $ref: '#/components/schemas/BatchPredictionStatus' model: $ref: '#/components/schemas/BatchPredictionModel' completion_window: type: string enum: - 24h description: Requested completion window. created_at: type: string format: date-time description: ISO timestamp when the batch was created. expires_at: type: string format: date-time description: ISO timestamp when the batch completion window expires. in_progress_at: type: string format: date-time nullable: true description: >- ISO timestamp when the batch entered `in_progress`, or `null` if it has not. finalizing_at: type: string format: date-time nullable: true description: >- ISO timestamp when the batch entered `finalizing`, or `null` if it has not. completed_at: type: string format: date-time nullable: true description: >- ISO timestamp when the batch reached `completed`, or `null` otherwise. failed_at: type: string format: date-time nullable: true description: ISO timestamp when the batch reached `failed`, or `null` otherwise. cancelling_at: type: string format: date-time nullable: true description: ISO timestamp when cancellation was requested, or `null` otherwise. cancelled_at: type: string format: date-time nullable: true description: >- ISO timestamp when the batch reached `cancelled`, or `null` otherwise. expired_at: type: string format: date-time nullable: true description: ISO timestamp when the batch reached `expired`, or `null` otherwise. request_counts: $ref: '#/components/schemas/BatchPredictionRequestCounts' metadata: $ref: '#/components/schemas/Metadata' error: allOf: - $ref: '#/components/schemas/ProblemDetails' nullable: true description: >- Batch-level terminal error details for `failed`, `cancelled`, or `expired` batches; otherwise `null`. results_url: type: string format: uri-reference nullable: true description: >- Relative URL for the NDJSON results stream once the batch is terminal. This becomes `null` after retained result lines are cleaned up. example: 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 ProblemDetails: type: object required: - type - title - status properties: type: type: string format: uri title: type: string status: type: integer detail: type: string instance: type: string format: uri-reference ValidationProblemDetails: allOf: - $ref: '#/components/schemas/ProblemDetails' - type: object required: - errors properties: errors: type: array description: >- Field-level validation issues. Item-level issues may include `custom_id` when Datagrid can associate the issue with a submitted item. items: $ref: '#/components/schemas/ValidationProblemError' BatchPredictionModel: type: string description: >- 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. enum: - 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 BatchPredictionItemInput: type: object required: - custom_id - file_id properties: custom_id: type: string minLength: 1 maxLength: 128 description: >- Caller-defined identifier. Must be unique within the batch and is echoed in result lines. file_id: type: string minLength: 1 description: >- Existing Datagrid file id from the Files API. The file must be accessible from the authenticated teamspace. page: type: integer minimum: 1 nullable: true description: Optional 1-indexed page number for a paged document such as a PDF. Metadata: type: object description: >- Optional metadata map with up to 16 entries. Metadata keys must be 64 characters or fewer and values must be 512 characters or fewer. maxProperties: 16 additionalProperties: type: string maxLength: 512 nullable: true BatchPredictionStatus: type: string description: >- Current batch lifecycle state. Terminal states are `completed`, `failed`, `expired`, and `cancelled`. enum: - validating - failed - in_progress - finalizing - completed - expired - cancelling - cancelled BatchPredictionRequestCounts: type: object required: - total - processing - succeeded - errored - canceled - expired properties: total: type: integer minimum: 0 description: Total number of submitted items. processing: type: integer minimum: 0 description: Items that are still pending or processing. succeeded: type: integer minimum: 0 description: Items that completed with a valid output. errored: type: integer minimum: 0 description: Items that ended with an error. canceled: type: integer minimum: 0 description: Items that were cancelled before completion. expired: type: integer minimum: 0 description: Items that did not finish before the completion window elapsed. description: >- The sum of processing, succeeded, errored, canceled, and expired equals total. ValidationProblemError: type: object required: - pointer - code - message properties: pointer: type: string description: JSON Pointer to the invalid request field. code: type: string description: Machine-readable validation code. message: type: string description: Human-readable validation message. custom_id: type: string nullable: true description: >- Submitted item `custom_id` associated with this issue, when available. securitySchemes: BearerAuth: type: http scheme: bearer ````