Batch Executions API

This API allows managing batch workflow executions. It provides endpoints to create, list, update, and obtain detailed information about executions, including their inputs, outputs, and statuses.

The ExecutionBatch Object

The ExecutionBatch object represents a workflow execution in the system.

{
    "id": "2d66b1df-9d12-4c21-852d-32820ec50b28",
    "status": "complete",
    "callbackAt": "2024-12-11T22:44:12.751000",
    "state": {
        "batchItemsExecutionsSummary": {
                "expected": 123,
                "pending": 0,
                "failed": 0,
                "success": 123,
                "unsuccessfulSources": 1
            },
            "preProcessingRetries": 0,
            "postProcessingRetries": 0,
            "batchItemsOutputsGenerating": false,
            "batchItemsOutputsPackageId": "1995fee3-5b89-456c-a77e-5fd8091edfc5",
            "preProcessingStartedAt": "2025-02-03T16:39:01.404336",
            "postProcessingStartedAt": "2025-02-03T16:41:05.855716",
            "processingStartedAt": "2025-02-03T16:40:01.628956",
            "batchItemsOutputsGenerationStartedAt": "2025-02-03T16:41:02.012355",
            "preparingBatchItemsRetry": false
   },
    "label": "kyc batch test",
    "description": "A batch of 100 items to run KYC",
    "workflowId": "072386f4-42c1-4685-ad5f-35a724486b24",
    "workflowAlias": "kyc",
    "workflowVersion": "v0",
    "settings": {
        "maxExecutionsPerSecond": 1.0,
        "maxConcurrentDispatches": 1,
        "maxItemExecutionRuns": 2
    },
    "unsuccessfulSources": true,
    "isBillable": false,
    "tags": [],
    "principalId": "developer@altscore.ai",
    "createdAt": "2024-12-11T17:43:12.752000",
    "finishedAt": "2024-12-12T00:01:03.042000",
    "inputs": {
        "items": [],
        "customInput": {},
        "rawPackageIds": ["2ce5110b-2c45-4f48-87f5-aab469244d9a"]
    },
    "outputs": {
        "wBatchPreProcessingOutput": {
            "processedInputPackageId": "3db19066-c581-42f3-b193-a0f86201d510",
            "itemCount": 123,
            "result": "success",
            "notices": []
        },
        "wBatchPostProcessingOutput": {
            "processedOutputPackageId": "b963707f-d572-4527-8732-c5af816e29de",
            "itemCount": 123,
            "result": "success",
            "notices": []
        }
    },
    "debug": false
}

Attributes

Attribute	Description	Type
id	Unique identifier of the batch execution	String
principalId	ID of the user who initiated the batch execution	String
label	Short label describing the batch execution (optional)	String
description	Description of the batch execution (optional)	String
workflowId	ID of the executed workflow	String
workflowAlias	Alias of the workflow	String
workflowVersion	Version of the workflow	String
status	Current status of the batch execution	String
isBillable	Indicates whether the batch execution is billable (optional)	Boolean
tags	Tags associated with the batch execution	Array of String
createdAt	Creation date and time of the execution	String (ISO 8601)
finishedAt	Completion date and time of the execution (optional)	String (ISO 8601)
callbackAt	Scheduled date and time for execution start (optional)	String (ISO 8601)
settings	Settings for the batch processing orchestrator (optional)	Object
unsuccessfulSources	Indicates whether the execution of at least one batch item failed to obtain data from any of its target data sources (optional)	Boolean
inputs	Object with the execution input data	Object
outputs	Object with the execution output data (optional)	Object
debug	Indicates whether the batch execution is in debug mode (optional)	Boolean

The settings field may contain the following configurations:

Attribute	Description	Type
maxExecutionsPerSecond	Maximum number of executions per second allowed (optional)	Float
maxConcurrentDispatches	Maximum number of concurrent executions allowed (optional)	Integer
maxItemExecutionRuns	Maximum number of executions (including auto-retries) allowed per batch item before declaring the item as failed (optional)	Integer

Operations

List Batches

Retrieves a paginated list of batches with filtering and sorting options.

GET /v1/execution-batches

Query Parameters

Parameter	Description	Type
billable-id	Filter by billable ID	String
workflow-id	Filter by workflow ID	String
workflow-version	Filter by workflow version	String
workflow-alias	Filter by workflow alias	String
workflow-type	Filter by workflow type	String
page	Page number (default: 1)	Integer
per-page	Items per page (default: 10)	Integer
search	Text to search in executions	String
sort-by	Field to sort by	String
sort-direction	Sorting direction (asc or desc)	String
tags	Filter by tags	String
date-from	Start date for filtering	String
date-to	End date for filtering	String
status	Filter by execution status	String
exclude-tests	Exclude test and debug executions	Boolean

Successful Response

The response will be a paginated list of ExecutionBatch objects.

Get Batch Information

Retrieves detailed information about the batch.

GET /v1/execution-batch/:execution_batch_id

Path Parameters

Parameter	Description
execution_batch_id	ID of the batch to retrieve

Successful Response

The response will be an ExecutionBatch object.

Retry Batch

Retries a specific batch.

POST /v1/execution-batches/:execution_batch_id/retry

Path Parameters

Parameter	Description
execution_batch_id	ID of the batch to retry

Input Parameters

Parameter	Description	Type
retryMode	Retry mode of the batch execution. Can be "pre_processing", "post_processing", "failed_items", "unsuccessful_sources" or "failed_and_unsuccessful_sources_items"	String
usePreviousInputs	Indicates whether to reuse the input data from the previous execution. Can be "true" or "false"	String
workflowInput	Input data	Object
attachmentFileNames	Names of attachment files with information about the batch items	Array

The workflowInput JSON should have the structure described below:

Field	Description	Type
items	A list of dictionaries with input data for the execution of each batch item. This field is designed for quick testing of up to 10 items	Array
rawPackageIds	A list of previously created package IDs containing attachment files with information about the batch items that will be read, validated, and processed in the batch execution. Up to 5 packages can be sent	Array
customInput	Custom formatted input	Object

Request Example

curl --location '{base_url}/v1/execution-batches/{execution_batch_id}/retry' \
--header 'Authorization: Bearer {token}' \
--data '
{
    "retryMode": "pre_processing",
    "usePreviousInputs": false,
    "workflowInput": {
        "items": [
            { "person_id": "9999999999" },
            { "person_id": "1234567890" }
        ],
        "customInput": {},
        "rawPackageIds": []
    }
}
'

Successful Response

The response will include information about the batch execution retry.

Pause Batch

Pauses the processing of a batch.

POST /v1/execution-batches/:execution_batch_id/pause

Path Parameters

Parameter	Description
execution_batch_id	ID of the execution to pause

Successful Response

HTTP 200.

Resume Batch

Resumes the processing of a paused batch.

POST /v1/execution-batches/:execution_batch_id/resume

Path Parameters

Parameter	Description
execution_batch_id	ID of the execution to resume

Successful Response

HTTP 200.

Cancel Batch

Cancels the processing of a batch.

POST /v1/execution-batches/:execution_batch_id/cancel

Path Parameters

Parameter	Description
execution_batch_id	ID of the execution to cancel

Successful Response

HTTP 200.

Error Handling

The API may return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
500	Internal Server Error

Errors will include a descriptive message in the response body.

On this page