Batches API

The Batches API allows you to manage and process large-scale batch operations for your AI workflows on the Lumea platform.

Overview

Batch processing enables you to run multiple instances of the same workflow with different input parameters in parallel. This is useful for processing large datasets, running evaluations across multiple inputs, or performing bulk operations. The Batches API provides endpoints to create, monitor, and manage these batch operations efficiently.

Note: Each customer receives a custom deployment with a unique API endpoint. The endpoints described in this documentation should be prefixed with your organization's specific API URL provided during onboarding.

Data Models

WorkflowBatch Object

Field	Type	Description
id	string	Unique identifier for the batch
workflow_id	string	ID of the workflow being executed in batch
label	string	Optional user-defined label for the batch
status	string	Current status of the batch (pending, running, completed, failed, stopped)
total_runs	integer	Total number of workflow runs in this batch
completed_runs	integer	Number of completed workflow runs
failed_runs	integer	Number of failed workflow runs
created_at	string	Timestamp when the batch was created
updated_at	string	Timestamp when the batch was last updated

Endpoints

Start Workflow Batch

Initiates a new batch of workflow runs.

URL: /batches

Method: POST

Request Body:

{
  "workflow_id": "workflow123",
  "label": "Monthly evaluation batch",
  "job_ids": ["job1", "job2", "job3"],
  "inputs": [
    {
      "parameter1": "value1",
      "parameter2": 100
    },
    {
      "parameter1": "value2",
      "parameter2": 200
    },
    {
      "parameter1": "value3",
      "parameter2": 300
    }
  ]
}

Field	Type	Required	Description
workflow_id	string	Yes	ID of the workflow to execute in batch
label	string	No	Optional label for the batch
job_ids	array	No	Optional array of job IDs to associate with each run
inputs	array	Yes	Array of input objects, one for each run in the batch

Success Response:

• Code: 200 OK
• Content:

{
  "id": "batch123",
  "workflow_id": "workflow123",
  "label": "Monthly evaluation batch",
  "status": "pending",
  "total_runs": 3,
  "completed_runs": 0,
  "failed_runs": 0,
  "created_at": "2023-06-01T12:00:00Z",
  "updated_at": "2023-06-01T12:00:00Z"
}

Error Response:

• Code: 400 Bad Request
  • Content: {"detail": "Error message"}

Get Workflow Batch

Retrieves details of a specific workflow batch.

URL: /batches/{batch_id}

Method: GET

URL Parameters:

Parameter	Description
batch_id	The unique ID of the batch

Success Response:

• Code: 200 OK
• Content:

{
  "id": "batch123",
  "workflow_id": "workflow123",
  "label": "Monthly evaluation batch",
  "status": "running",
  "total_runs": 3,
  "completed_runs": 1,
  "failed_runs": 0,
  "created_at": "2023-06-01T12:00:00Z",
  "updated_at": "2023-06-01T12:01:00Z"
}

Error Response:

• Code: 400 Bad Request
  • Content: {"detail": "Error message"}

Get Batch Outputs

Retrieves the outputs from all successfully completed runs in a batch.

URL: /batches/{batch_id}/outputs

Method: GET

URL Parameters:

Parameter	Description
batch_id	The unique ID of the batch

Success Response:

• Code: 200 OK
• Content:

{
  "outputs": [
    {
      "result": "Success for run 1",
      "metrics": {
        "accuracy": 0.95,
        "latency": 0.23
      }
    },
    {
      "result": "Success for run 2",
      "metrics": {
        "accuracy": 0.92,
        "latency": 0.19
      }
    }
  ],
  "job_ids": ["job1", "job2"]
}

Error Response:

• Code: 400 Bad Request
  • Content: {"detail": "Error message"}

Get Batch Runs

Retrieves all workflow runs associated with a specific batch.

URL: /batches/{batch_id}/runs

Method: GET

URL Parameters:

Parameter	Description
batch_id	The unique ID of the batch

Query Parameters:

Parameter	Required	Description
include	No	Comma-separated list of fields to include (e.g., "state")

Success Response:

• Code: 200 OK
• Content:

[
  {
    "id": "run123",
    "workflow_id": "workflow123",
    "batch_id": "batch123",
    "job_id": "job1",
    "status": "success",
    "inputs": {
      "parameter1": "value1",
      "parameter2": 100
    },
    "outputs": {
      "result": "Success for run 1",
      "metrics": {
        "accuracy": 0.95,
        "latency": 0.23
      }
    },
    "created_at": "2023-06-01T12:00:00Z",
    "updated_at": "2023-06-01T12:05:00Z"
  },
  {
    "id": "run124",
    "workflow_id": "workflow123",
    "batch_id": "batch123",
    "job_id": "job2",
    "status": "success",
    "inputs": {
      "parameter1": "value2",
      "parameter2": 200
    },
    "outputs": {
      "result": "Success for run 2",
      "metrics": {
        "accuracy": 0.92,
        "latency": 0.19
      }
    },
    "created_at": "2023-06-01T12:00:00Z",
    "updated_at": "2023-06-01T12:10:00Z"
  },
  {
    "id": "run125",
    "workflow_id": "workflow123",
    "batch_id": "batch123",
    "job_id": "job3",
    "status": "running",
    "inputs": {
      "parameter1": "value3",
      "parameter2": 300
    },
    "created_at": "2023-06-01T12:00:00Z",
    "updated_at": "2023-06-01T12:01:00Z"
  }
]

Error Response:

• Code: 400 Bad Request
  • Content: {"detail": "Error message"}

Stop Workflow Batch

Stops all running workflow executions in a batch.

URL: /batches/{batch_id}/stop

Method: POST

URL Parameters:

Parameter	Description
batch_id	The unique ID of the batch

Success Response:

• Code: 200 OK
• Content:

{
  "message": "Batch stopped successfully"
}

Error Response:

• Code: 400 Bad Request
  • Content: {"detail": "Error message"}

List Workflow Batches

Retrieves a list of workflow batches with optional filtering.

URL: /batches

Method: GET

Query Parameters:

Parameter	Required	Description
status	No	Filter batches by status
workflow_id	No	Filter batches by workflow ID

Success Response:

• Code: 200 OK
• Content:

[
  {
    "id": "batch123",
    "workflow_id": "workflow123",
    "label": "Monthly evaluation batch",
    "status": "completed",
    "total_runs": 3,
    "completed_runs": 3,
    "failed_runs": 0,
    "created_at": "2023-06-01T12:00:00Z",
    "updated_at": "2023-06-01T12:15:00Z"
  },
  {
    "id": "batch456",
    "workflow_id": "workflow456",
    "label": "Weekly test batch",
    "status": "running",
    "total_runs": 5,
    "completed_runs": 2,
    "failed_runs": 1,
    "created_at": "2023-06-02T12:00:00Z",
    "updated_at": "2023-06-02T12:10:00Z"
  }
]

Error Response:

• Code: 400 Bad Request
  • Content: {"detail": "Error message"}