batches

Creates, updates, deletes, gets or lists a batches resource.

Overview

Name	batches
Type	Resource
Id	digitalocean.inference.batches

Fields

The following fields are returned by SELECT queries:

inference_get_batch

The batch job.

Name	Datatype	Description
batch_id	string (uuid)	Unique identifier for the batch job. (example: 0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21)
error_file_id	string (uuid)	Error sidecar file. Null when no errors were produced.
input_file_id	string (uuid)	The uploaded JSONL input file. (example: a1b2c3d4-e5f6-4789-90ab-cdef12345678)
output_file_id	string (uuid)	Output JSONL file. Populated once the job completes.
request_id	string	The idempotency key supplied at creation. (example: c7e3ad1e-20c3-4e47-9bf2-6f2a4d6a2f11)
cancelled_at	string (date-time)	(example: 2026-04-24T19:45:11Z)
completed_at	string (date-time)	(example: 2026-04-24T20:15:30Z)
completion_window	string	(24h) (example: 24h)
created_at	string (date-time)	(example: 2026-04-24T19:19:19Z)
endpoint	string	Inference endpoint each request is dispatched to. (example: /v1/chat/completions)
errors	array	Top-level errors that prevented the batch from completing.
expires_at	string (date-time)	Derived from created_at plus completion_window. (example: 2026-04-25T19:19:19Z)
failed_at	string (date-time)	(example: 2026-04-24T19:50:00Z)
finalizing_at	string (date-time)	(example: 2026-04-24T20:10:42Z)
in_progress_at	string (date-time)	(example: 2026-04-24T19:20:05Z)
metadata	object	Metadata attached at creation.
provider	string	(openai, anthropic) (example: openai)
request_counts	object	Aggregate request counts.
status	string	Lifecycle status. Terminal states: completed, failed, expired, cancelled. (validating, in_progress, finalizing, completed, failed, expired, cancelling, cancelled) (example: in_progress)

inference_list_batches

Page of batch jobs.

Name	Datatype	Description
batch_id	string (uuid)	Unique identifier for the batch job. (example: 0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21)
error_file_id	string (uuid)	Error sidecar file. Null when no errors were produced.
input_file_id	string (uuid)	The uploaded JSONL input file. (example: a1b2c3d4-e5f6-4789-90ab-cdef12345678)
output_file_id	string (uuid)	Output JSONL file. Populated once the job completes.
request_id	string	The idempotency key supplied at creation. (example: c7e3ad1e-20c3-4e47-9bf2-6f2a4d6a2f11)
cancelled_at	string (date-time)	(example: 2026-04-24T19:45:11Z)
completed_at	string (date-time)	(example: 2026-04-24T20:15:30Z)
completion_window	string	(24h) (example: 24h)
created_at	string (date-time)	(example: 2026-04-24T19:19:19Z)
endpoint	string	Inference endpoint each request is dispatched to. (example: /v1/chat/completions)
errors	array	Top-level errors that prevented the batch from completing.
expires_at	string (date-time)	Derived from created_at plus completion_window. (example: 2026-04-25T19:19:19Z)
failed_at	string (date-time)	(example: 2026-04-24T19:50:00Z)
finalizing_at	string (date-time)	(example: 2026-04-24T20:10:42Z)
in_progress_at	string (date-time)	(example: 2026-04-24T19:20:05Z)
metadata	object	Metadata attached at creation.
provider	string	(openai, anthropic) (example: openai)
request_counts	object	Aggregate request counts.
status	string	Lifecycle status. Terminal states: completed, failed, expired, cancelled. (validating, in_progress, finalizing, completed, failed, expired, cancelling, cancelled) (example: in_progress)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
inference_get_batch	select	batch_id		Returns the current state of a batch job. Poll until status reaches a terminal value (completed, failed, expired, or cancelled).
inference_list_batches	select		after, limit, status	Returns a cursor-paginated list of batch jobs, ordered newest first. Use limit to control page size and after to page forward using the last_id from the previous response.
inference_create_batch	insert	file_id, provider, completion_window, request_id		Submits a batch job against a previously uploaded JSONL input file. The upload must have completed before this call; otherwise the request is rejected. Supply a unique request_id to make the submission idempotent — retries with the same value return the existing job. When provider is openai, the url on each JSONL line must match endpoint.
inference_cancel_batch	exec	batch_id		Requests cancellation of a batch job. The job transitions to cancelling and, once in-flight requests drain, to cancelled. Jobs already in a terminal state (completed, failed, expired, cancelled) cannot be cancelled and return 409 Conflict. Cancellation is also rejected with 409 Conflict while the job has not yet been submitted to the upstream provider — there is nothing to cancel until the provider batch id is assigned. Partial results produced before cancellation remain available via GET /v1/batches/{batch_id}/results.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
batch_id	string (uuid)	The batch job identifier. (example: 0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21)
after	string (uuid)	Cursor for pagination. Pass the last_id value from the previous response to fetch the next page. Omit for the first page. (example: 7b2e9c1a-6f4d-4d9b-a0f1-5c4b7e2f8a12)
limit	integer	Maximum number of batches to return per page. (example: 20)
status	string	Optional filter restricting results to batches in the given lifecycle state. (example: in_progress)

SELECT examples

inference_get_batch

Returns the current state of a batch job. Poll until status reaches a terminal value (completed, failed, expired, or cancelled).

SELECT
batch_id,
error_file_id,
input_file_id,
output_file_id,
request_id,
cancelled_at,
completed_at,
completion_window,
created_at,
endpoint,
errors,
expires_at,
failed_at,
finalizing_at,
in_progress_at,
metadata,
provider,
request_counts,
status
FROM digitalocean.inference.batches
WHERE batch_id = '{{ batch_id }}' -- required
;

inference_list_batches

Returns a cursor-paginated list of batch jobs, ordered newest first. Use limit to control page size and after to page forward using the last_id from the previous response.

SELECT
batch_id,
error_file_id,
input_file_id,
output_file_id,
request_id,
cancelled_at,
completed_at,
completion_window,
created_at,
endpoint,
errors,
expires_at,
failed_at,
finalizing_at,
in_progress_at,
metadata,
provider,
request_counts,
status
FROM digitalocean.inference.batches
WHERE after = '{{ after }}'
AND limit = '{{ limit }}'
AND status = '{{ status }}'
;

INSERT examples

inference_create_batch

Submits a batch job against a previously uploaded JSONL input file. The upload must have completed before this call; otherwise the request is rejected.

Supply a unique request_id to make the submission idempotent — retries with the same value return the existing job. When provider is openai, the url on each JSONL line must match endpoint.

INSERT INTO digitalocean.inference.batches (
file_id,
provider,
endpoint,
completion_window,
request_id,
metadata
)
SELECT 
'{{ file_id }}' /* required */,
'{{ provider }}' /* required */,
'{{ endpoint }}',
'{{ completion_window }}' /* required */,
'{{ request_id }}' /* required */,
'{{ metadata }}'
RETURNING
batch_id,
error_file_id,
input_file_id,
output_file_id,
request_id,
cancelled_at,
completed_at,
completion_window,
created_at,
endpoint,
errors,
expires_at,
failed_at,
finalizing_at,
in_progress_at,
metadata,
provider,
request_counts,
status
;

Manifest

# Description fields are for documentation purposes
- name: batches
props:
  - name: file_id
    value: "{{ file_id }}"
    description: |
      The `file_id` returned by `POST /v1/batches/files`.
  - name: provider
    value: "{{ provider }}"
    description: |
      The inference provider whose JSONL schema the input file conforms to. `openai` follows the OpenAI Batch API input schema (`custom_id`, `method`, `url`, `body`); `anthropic` follows the Anthropic Message Batches JSONL conventions.
    valid_values: ['openai', 'anthropic']
  - name: endpoint
    value: "{{ endpoint }}"
    description: |
      Inference endpoint each request is dispatched to. **Required when `provider` is `openai` and must match the `url` on every JSONL line. Must be omitted when `provider` is `anthropic`.**
    valid_values: ['/v1/responses', '/v1/chat/completions']
  - name: completion_window
    value: "{{ completion_window }}"
    description: |
      Time window in which the job must complete. Jobs that do not finish in time transition to `expired`.
    valid_values: ['24h']
    default: 24h
  - name: request_id
    value: "{{ request_id }}"
    description: |
      Client-supplied idempotency key. Retries with the same value return the existing job instead of creating a duplicate.
  - name: metadata
    value: "{{ metadata }}"
    description: |
      Optional string-valued metadata to attach to the job.

Lifecycle Methods

inference_cancel_batch

Requests cancellation of a batch job. The job transitions to cancelling and, once in-flight requests drain, to cancelled. Jobs already in a terminal state (completed, failed, expired, cancelled) cannot be cancelled and return 409 Conflict. Cancellation is also rejected with 409 Conflict while the job has not yet been submitted to the upstream provider — there is nothing to cancel until the provider batch id is assigned.

Partial results produced before cancellation remain available via GET /v1/batches/{batch_id}/results.

EXEC digitalocean.inference.batches.inference_cancel_batch 
@batch_id='{{ batch_id }}' --required
;