Compute Tasks

What is a Compute Task? What is the Task API?

A Compute Task is a logical component implementing a computation on data in Evo that requires variable on-demand processing power.

The Evo compute platform's Task API provides functionality to run compute tasks. Task API exposes endpoints to:

• Execute a task. This operation spawns a job, a running instance of the executed task.
• Check job status
• Check job results
• Cancel a job

API operations

Please refer to the Compute Task API reference for a detailed description of the endpoints.

Execute Task

The Execute Task operation is designed to initiate a compute task. By making a POST request to the specified endpoint, you can execute a compute task with your parameters. This is also known as creating a job.

Endpoint

POST https://{hub}.api.seequent.com/compute/orgs/<org_id>/<topic>/<task>

This endpoint allows you to execute a compute task by specifying the org_id, topic, and task*in the URL. The hub placeholder should be replaced with the appropriate hub identifier to direct the request to the correct location.

Request Body

The request body must include a JSON object named parameters, which contains key-value pairs representing the task's input parameters.

{
    "parameters": {
        "name_parameter_1": "value_parameter_1",
        "name_parameter_2": {
           // Additional nested parameters can be included here
        },
        // Additional parameters can be added as needed
    }
}

Response

Upon successfully receiving and processing the request, the server responds with a 303 See Other HTTP status code. This response includes a Location header, which provides the URL to poll for the status of the submitted compute job.

Get Status

The Get Status operation allows you to query the current status of a compute job.

Endpoint

GET https://{hub}.api.seequent.com/compute/orgs/<org_id>/<topic>/<task>/<job_id>/status

Use this endpoint to check the status of a job by providing the org_id, topic, task, and job_id. The job_id is the unique identifier returned by the Execute Task endpoint when submitting the job.

Response

The server responds with different HTTP status codes and body content based on the current state of the job:

• 202 Accepted: The job is still in progress. This indicates that the job has been submitted and is currently being processed, but has not yet been completed.

• 200 OK: The job has been completed. The response body will include detailed information about the job's status and results, including whether it succeeded, failed, or was canceled.

The response body contains the following information:

• status: A string indicating the current state of the job. Possible values include requested, in_progress, canceling, succeeded, failed, canceled.
• progress: A numerical value between 0-100 indicating the job's progress towards completion.
• message: A string providing a human-readable description of the current progress. This can be useful for displaying to end-users for insight into the progress.
• error: If the job fails, this field may contain an error message or code providing more details about the failure.

Get Result

The Get Result operation helps you retrieve the final output of the compute job after its completion.

Endpoint

GET https://{hub}.api.seequent.com/compute/orgs/<org_id>/<topic>/<task>/<job_id>/result

Using this endpoint, you can fetch the result of a compute task by specifying the org_id, topic, task, and job_id. The job_id is the unique identifier provided by the Execute Task endpoint when submitting the job.

Response

The server's response to this request will vary depending on the nature of the task's output. However, it typically includes a 200 OK HTTP status code, indicating successful retrieval of the result.

Cancel Task

The Cancel Task operation cancels a compute task that is currently in requested or in_progress phase. This is particularly useful for stopping long-running jobs that are no longer needed. However, the termination of a job that is already in progress is not guaranteed. For more information on how the cancellation of a job works, please refer to the documentation for the task.

Endpoint

POST https://{hub}.api.seequent.com/compute/orgs/<org_id>/<topic>/<task>/<job_id>/cancel

Using this endpoint, you may request the cancellation of a job by providing the org_id,topic ,task, and job_id. The job_id is a unique identifier for the task instance, assigned by the system when the task is initiated.

Request

The request to cancel a task does not typically require a body. The action is initiated simply by sending a POST request to the specified endpoint with the appropriate identifiers in the URL.

Response

Upon successfully receiving the cancellation request, the server responds with a 202 Accepted HTTP status code. This indicates that the request has been accepted and the system will attempt to cancel the task.

However, if the task has already reached a terminal state (succeeded or failed), the server will respond with a 422 Unprocessable Entity status code. This response indicates that the cancellation request cannot be processed because the task is no longer in a state that can be canceled.