​
Reason to use

For Tasks that you wish to run multiple times, the Async API is a great way to improve latency. Asynchronous operations allow multiple runs to be executed simulataneously, rather than sequentially. This means that while one execution is waiting to be completed, other runs can continue to execute. This can significantly improve your experience while using the Task API for large datasets.

The Task API supports polling and callback for individual Runs.

​
Process

Here is a step-by-step guide on how to use the Async Runs feature:

  1. First create a Task as you typically would.
curl -X POST <https://api.parallel.ai/v0/tasks> \
    -H "x-api-key: $PARALLEL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '
    {
            "name": "CEO Task",
            "prompt": "Who is the CEO of ${company}",
            "input_schema": {
                "properties": {
                    "company": {"type": "string"}
                },
                "required": ["company"],
                "type": "object"
            },
            "output_schema": {
                "type": "object",
                "properties": {"answer": {"type": "string"}}
            },
            "processor": "argon"
    }'
  1. Post request with an extra argument enqueue_run set to true to the Task API.
// Replace TASK_ID with the task ID returned in your specific use case
curl -X POST <https://api.parallel.ai/v0/tasks/0146b432-c081-430b-bb82-56c114499bb1/runners/argon/runs> \
    -H "x-api-key: $PARALLEL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '
    {
        "arguments" : {"company": "OpenAI"},
        "enqueue_run": true
    }
  1. Poll the Run API to check the status of the Run. Once the run is complete, you can retrieve the results. More information on polling and callbacks can be found below.

​
Polling

To access the newly created Run, you can poll the Run API. Send a GET request:

curl https://api.parallel.ai/v0/tasks/${TASK_ID}/runs/${RUN_ID}

Below are the possible statuses for a Run:

  • queued: The run has been queued and is waiting to be processed.
  • running: The run is currently being processed.
  • awaiting_tool_calls: The run is waiting for tool calls to complete.
  • complete: The run has completed.
  • failed: The run has failed.
  • cancelling: cancellation requested; may still be running
  • cancelled: The run has been cancelled.

​
Callback

To add a callback, use the callback_webhook argument in the Task API.

// Replace TASK_ID with the task ID returned in your specific use case

curl -X POST https://api.parallel.ai/v0/tasks/0146b432-c081-430b-bb82-56c114499bb1/runners/argon/runs \
 -H "x-api-key: $PARALLEL_API_KEY" \
 -H "Content-Type: application/json" \
 -d '
 {
         "arguments" : {"company": "OpenAI"},
         "enqueue_run": true,
         "callback_webhook": {"url": https://webhook.com, secret:"secret", "headers": {"Authorization": "Bearer your_secret_key"}}
 }

We will send a post request to the URL provided once the run completes.

​
Note on Secrets

Secret is an optional field that can be used as an additional layer of security to check if the webhook call is coming from Parallel.

To verify that the message is correct and from us, you can do the equivalent of the following python code on the webhook server:

hmac_signature = headers["X-Authorization-Content-HMAC"]
expected_signature = hmac.new(
    key=b"secret",
    msg=json.dumps(webhook_data).encode(),
    digestmod=hashlib.sha256,
).hexdigest()
assert hmac_signature == expected_signature

​
Note on headers

The headers are an optional field that can be used for authorizing parallel on the webhook server. For example, if your webhook server uses JWT, you can pass in the JWT token as a part of the headers into the callback webhook. Parallel will call the webhook server with these headers.