Tasks and Discovery

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 run, a running instance of the executed task.
• Check run status
• Check run results
• Cancel a run

Compute Discovery API?

The Evo compute platform's Discovery API provides functionality to list existing compute tasks

API operations

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

Task API

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 run.

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 run.

Get Status

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

Endpoint

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

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

Response

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

• 202 Accepted: The run is still in progress. This indicates that the run has been submitted and is currently being processed, but has not yet been completed.
• 200 OK: The run has been completed. The response body will include detailed information about the run'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 run. Possible values include requested, in_progress, canceling, succeeded, failed, canceled.
• progress: A numerical value between 0-100 indicating the run'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 run 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 run after its completion.

Endpoint

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

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

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 run that is already in progress is not guaranteed. For more information on how the cancellation of a run works, please refer to the documentation for the task.

Endpoint

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

Using this endpoint, you may request the cancellation of a run by providing the org_id,topic ,task, and run_id. The run_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 DELETE request to the specified endpoint with the appropriate identifiers in the URL.

Response

Upon successfully receiving the cancellation request, the server responds with a 204 No Content 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.

Discovery API

List Tasks

The List Tasks operation retrieves a paginated list of task metadata available for the organization. It can be filtered using query parameters on the topic name, task name, or unique task key.

Endpoint

GET https://{hub}.api.seequent.com/compute/orgs/<org_id>/tasks

Query Parameters

Filter the list of tasks returned on:

• key: unique. Only supports a single key
  • ?key=<key>
• topic: topic name. Can be queried directly or using in operator to pass multiple topic names.
  • ?topic=topic1
  • ?topic=in:topic1,topic2
• name: task name. Can be queried directly or using in operator to pass multiple task names.
  • ?name=task1
  • ?name=in:task1,task2

Paginate results with:

• limit: number of results to return
• offset: number of results to skip

Increase the information in the response with:

• details: boolean. determines how verbose the response is (keys returned in responses)
  • ?details=false
  • When set to false parameters, results and links fields are excluded from the response

Response

Upon successfully receiving and processing the request, the server responds with a 200 OK HTTP status code. This response includes a metadata list of tasks that meet the query criteria and the limit, offset, total and count pagination details.