Retrieve batch prediction

Retrieves a batch prediction by id. Terminal batches include a results_url until retained result lines are cleaned up.

GET /batch-predictions/{batch_prediction_id}

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.retrieve(
    "batch_prediction_id",
)
print(batch_prediction.id)

200

{
  "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.

Path Parameters

batch_prediction_id · string · required

The id of the batch prediction to retrieve.

Response

200

application/json

Retrieved batch prediction

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.