Batch

View as Markdown

The AI Functions Asynchronous API lets you process large volumes of requests as a batch in a single call.

Get a batchGET /api/2.0/ai-functions/batches/{name}List batchesGET /api/2.0/ai-functions/batchesCreate a batchPOST /api/2.0/ai-functions/batchesCancel a batchPOST /api/2.0/ai-functions/batches/{name}/cancel

Batch object

The AI Functions Asynchronous API lets you process large volumes of requests as a batch in a single call.

namestringBetaOutput onlyIDImmutable

Output only. Identifier. Resource name of the batch, returned by create. Format: batch_<id>.

endpointstringBeta

The AI function, for example ai_parse_document.

input_refstringBeta

Unity Catalog volume path of the JSONL input file. Each line is one request, in the form {"custom_id": ..., "body": ...}. The file can hold up to 50,000 requests and be up to 200 MiB.

paramsobjectBeta

Parameters of the function other than its input, applied to every request in the batch, for example schema for ai_extract. Put function options, such as version, in a nested options object. For the parameters of each function, see AI Functions.

output_refstringBeta

Unity Catalog volume path to write the JSONL output file to. If the path is a directory, the file is <path>/<name>_output.jsonl.

statusstringBetaOutput only

Output only. The status of the batch.

Values:

• PENDING
• IN_PROGRESS
• FINALIZING
• COMPLETED
• CANCELLING
• CANCELLED
• FAILED

create_timestringBetaOutput only

Output only. The time when the batch was created.

request_countsobjectBetaOutput only

Output only. The number of requests in the batch, by result. Returned when you get a batch, not when you list batches.

Show child attributesHide child attributes

totalint64BetaOutput only

Output only. The number of requests in the batch.

succeededint64BetaOutput only

Output only. The number of requests that were processed successfully.

failedint64BetaOutput only

Output only. The number of requests that failed. The service does not retry them.

percent_completedoubleBetaOutput only

Output only. The percentage of requests that are processed, from 0 to 100. Returned when you get a batch, not when you list batches.

View as Markdown

The Batch object

{
  "name": "string",
  "endpoint": "string",
  "input_ref": "string",
  "params": {},
  "output_ref": "string",
  "status": "PENDING",
  "create_time": "string",
  "request_counts": {
    "total": 0,
    "succeeded": 0,
    "failed": 0
  },
  "percent_complete": 0
}

Get a batch Beta

GET /api/2.0/ai-functions/batches/{name}

Gets the latest status and progress of a batch.

API scopes: ai-functions

Parameters

namestringRequiredpath

Resource name of the batch. Format: batch_<id>.

Response

Returns the Batch object.

View as Markdown

Response

{
  "name": "string",
  "endpoint": "string",
  "input_ref": "string",
  "params": {},
  "output_ref": "string",
  "status": "PENDING",
  "create_time": "string",
  "request_counts": {
    "total": 0,
    "succeeded": 0,
    "failed": 0
  },
  "percent_complete": 0
}

List batches Beta

GET /api/2.0/ai-functions/batches

Lists the batches that the caller created in this workspace.

API scopes: ai-functions

Parameters

page_sizeint32query

Maximum number of batches to return in one page.

page_tokenstringquery

A page token from a previous call to list batches. Omit it to get the first page.

Response

Returns a list of Batch objects.

View as Markdown

Response

{
  "batches": [
    {
      "name": "string",
      "endpoint": "string",
      "input_ref": "string",
      "params": {},
      "output_ref": "string",
      "status": "PENDING",
      "create_time": "string",
      "request_counts": {},
      "percent_complete": 0
    }
  ],
  "next_page_token": "string"
}

Create a batch Beta

POST /api/2.0/ai-functions/batches

Creates a batch that runs an AI function on every request in a JSONL file on a Unity Catalog volume. The batch runs asynchronously. To follow its progress, get the batch.

API scopes: ai-functions

Request body

The batch to create.

endpointstringRequired

The AI function, for example ai_parse_document.

input_refstringRequired

Unity Catalog volume path of the JSONL input file. Each line is one request, in the form {"custom_id": ..., "body": ...}. The file can hold up to 50,000 requests and be up to 200 MiB.

paramsobject

Parameters of the function other than its input, applied to every request in the batch, for example schema for ai_extract. Put function options, such as version, in a nested options object. For the parameters of each function, see AI Functions.

output_refstringRequired

Unity Catalog volume path to write the JSONL output file to. If the path is a directory, the file is <path>/<name>_output.jsonl.

Response

Returns the Batch object.

View as Markdown

Request

{
  "endpoint": "string",
  "input_ref": "string",
  "params": {},
  "output_ref": "string"
}

Response

{
  "name": "string",
  "endpoint": "string",
  "input_ref": "string",
  "params": {},
  "output_ref": "string",
  "status": "PENDING",
  "create_time": "string",
  "request_counts": {
    "total": 0,
    "succeeded": 0,
    "failed": 0
  },
  "percent_complete": 0
}

Cancel a batch Beta

POST /api/2.0/ai-functions/batches/{name}/cancel

Starts the asynchronous cancellation of a batch. Requests in progress are drained first. Cancellation is best effort, so the batch can still complete.

API scopes: ai-functions

Parameters

namestringRequiredpath

Resource name of the batch. Format: batch_<id>.

View as Markdown

Response

{}