Job APIs enables creating, managing, monitoring, and analyzing jobs in Bacalhau.
Endpoint: GET /api/v1/orchestrator/jobs/:jobID
Retrieve the specification and current status of a particular job.
Parameters:
:jobID
: Identifier of the job to describe. This can be full ID of the job (e.g. j-28c08f7f-6fb0-48ed-912d-a2cb6c3a4f3a
) or just the short format (e.g. j-28c08f7f
) if it's unique.
Response:
Job: Specification for the requested job.
Example:
Endpoint: GET /api/v1/orchestrator/jobs
Retrieve a list of jobs.
Parameters:
namespace
: Specify a namespace to filter the jobs. Use *
to display jobs from all namespaces.
labels
: Use label-based criteria to filter jobs. See Label Filtering for usage details.
limit
: Set the maximum number of jobs to return. Default is set to 10.
next_token
: Utilize this parameter for pagination continuation.
order_by
: Determine the ordering of jobs. Choose between id
or create_time
(default is create_time
).
reverse
: Opt to reverse the default order of displayed jobs.
Response:
Jobs: List of matching jobs.
NextToken (string)
: Pagination token.
Example:
List jobs with limit set to 3:
List with label filtering
Endpoint: PUT /api/v1/orchestrator/jobs
Submit a new job for execution.
Request Body:
Job: JSON definition of the job.
Response:
JobID (string)
: Identifier for the new job.
EvaluationID (string)
: Identifier for the evaluation to schedule the job.
Warnings (string[])
: Any warnings during job submission.
Example:
Endpoint: DELETE /api/v1/orchestrator/jobs/:jobID
Terminate a specific job asynchronously.
Parameters:
:jobID
: Identifier of the job to describe. This can be full ID of the job (e.g. j-28c08f7f-6fb0-48ed-912d-a2cb6c3a4f3a
) or just the short format (e.g. j-28c08f7f
) if it's unique.
reason
: A message for debugging and traceability.
Response:
EvaluationID (string)
: Identifier for the evaluation to stop the job.
Example:
Endpoint: GET /api/v1/orchestrator/jobs/:jobID/history
Retrieve historical events for a specific job.
Parameters:
since
: Timestamp to start (default: 0).
event_type
: Filter by event type: job
, execution
, or all
(default).
execution_id
: Filter by execution ID.
node_id
: Filter by node ID.
limit
: Maximum events to return.
next_token
: For pagination.
Response:
History: List of matching historical events.
NextToken (string)
: Pagination token.
Example:
List events for a specific execution
Endpoint: GET /api/v1/orchestrator/jobs/:jobID/executions
Retrieve all executions for a particular job.
Parameters:
limit
: Maximum executions to return.
next_token
: For pagination.
order_by
: Order by modify_time
(default), create_time
, id
, state
.
reverse
: Reverse the order.
Response:
Executions: List of relevant executions.
NextToken (string)
: Pagination token.
Example
List executions for a batch job with 3 executions (i.e. count=3
)
Endpoint: GET /api/v1/orchestrator/jobs/:jobID/results
Fetch results published by all executions for the defined job. Applicable only for batch
and ops
jobs.
Response:
Results: List of all published results.
NextToken (string)
: Pagination token.
Example:
Result of a job that used the S3 Publisher: