DocumentationAPI referenceWhat's new
API reference

Job batch callbacks

When submitting jobs, the first entity users interact with is the job batch. The job batch represents a collection of jobs which get ingested into the super.AI platform. Before ingestion, we validate that the input data and parameters for correctness. In case of failure, it can happen that job ingestion fails. To react on successful and failed ingestions, its possible to enable event callbacks.

By enabling job batch events, you can receive notifications when a job batch has been fully ingested: Project Wide Callbacks Settings

The notification is a POST request to the specified URL. The payload of that request is formatted according to your V2 format schema.

⚠️

The URL for job batch events can only be specified in the project settings. Setting it in the job submission payload is not supported.

Callback payload format

Job batch events use our new callback schema (v2), which differs from the legacy job callbacks.

{  
  "version": "2",  
  "entityType": "batch",  
  "entityId": "af335590-4ed0-4b68-a08f-2faf5ecabea0",  
  "state": "COMPLETED",  
  "appId": "ff3174b3-b35a-464d-8329-85a81a13c21e"  
}

This new format is identified by the version field. Ensure that your logic explicitly handles entityType: batch to maintain compatibility with future updates.

  • The appId field represents your project’s (application’s) unique ID.
  • The state field indicates the final status of the batch processing:
    • COMPLETED: All jobs in the batch were ingested successfully
    • FAILED: No jobs in the batch could be ingested successfully
    • PARTIAL_FAILURE: Some jobs were ingested successfully, but others failed (only possible in non-strict mode)

To retrieve all jobs associated with a specific batch (entityId), use the Get job ids of batch API.


Find out why a batch failed

To inspect the error message, use the batch API with the entityId as batchId.