Skip to main content

Classic Asynchronous Workflow Example

This section describes the most common usage of the asynchronous endpoints.

The purpose of this flow is:

  1. Create a collection with multiple requests.
  2. Execute a Run for this collection.
  3. Query the run status until it completes.

1. Create a collection​

First, we create a collection that groups the requests we want to run asynchronously.

Endpoint​

POST /v1/async/collections

Request Body Example​

{
  "name": "new collection",
  "requests": [
    {
      "url": "www.google.com",
      "browser": true,
      "screenshot": false,
      "actions": [
        {
          "type": "wait-for-timeout",
          "time": 5000
        }
      ]
    },
    {
      "url": "www.example.com",
      "browser": true,
      "screenshot": false,
      "actions": [
        {
          "type": "wait-for-timeout",
          "time": 5000
        }
      ]
    }
  ]
}

Expected Response​

{
  "id": "c38b0bcf-cb7c-4728-8704-2c2e267dcff9",
  "name": "new collection",
  "message": "Collection created successfully."
}

At this point, the collection is ready to be executed. Save the collection_id as it will be needed for the following steps.

2. Create a Run for the Collection​

Once the collection has been created, we can start the Run execution.

A Run represents a single execution of the requests placed in the collection.

Endpoint​

POST /v1/async/collections/{collection_id}/run

Parameters​

No body is needed for this request, only the collection_id is required as a parameter.

Response Example​

{
  "run_id": "9b64941a-4545-4c57-9174-c70e781d9192",
  "status": "in_progress",
  "total_requests": 2,
  "success_requests": 0,
  "failed_requests": 0,
  "timeout_requests": 0,
  "collection_id": "c38b0bcf-cb7c-4728-8704-2c2e267dcff9"
}

The run is created and begins executing asynchronously.

  • The initial status always starts as in_progress.
  • The run_id uniquely identifies the execution and should be saved to track the Run.

3. Query the Run Status​

Since the run is asynchronous, the execution takes a variable amount of time depending on the number of requests and their complexity.

After a short wait, you can query the run status using the run_id.

Endpoint​

GET /v1/async/collections/{collection_id}/runs/{run_id}

Response Example (Still In Progress)​

{
  "run_id": "9b64941a-4545-4c57-9174-c70e781d9192",
  "status": "in_progress",
  "total_requests": 2,
  "success_requests": 1,
  "failed_requests": 0,
  "timeout_requests": 0,
  "collection_id": "c38b0bcf-cb7c-4728-8704-2c2e267dcff9"
}

This response indicates that the Run has started but has not finished.

4. Run Completed​

After waiting long enough, the query will return the completed run.

Response Example (Completed)​

{
  "run_id": "9b64941a-4545-4c57-9174-c70e781d9192",
  "status": "completed",
  "total_requests": 2,
  "success_requests": 2,
  "failed_requests": 0,
  "timeout_requests": 0,
  "collection_id": "c38b0bcf-cb7c-4728-8704-2c2e267dcff9"
}

At this point:

  • status is completed.
  • All requests defined in the collection have been processed.
  • The success_requests and failed_requests provide a summary of the execution and its result.

Summary​

This code flow follows a simple pattern that breaks down into 3 parts:

  1. Create a Collection With one or more requests.
  2. Start the Execution Run the collection asynchronously.
  3. Query the Run Status Using the run ID until it completes.