Runs

On this page we'll dive into the Runs endpoint you can use to execute Dust apps programmatically. We'll look at how to query, create, update, and delete runs.

Authentication

All requests to the Dust API must be authenticated using an Authentication header. The value of this header must be the string Bearer followed by a space and your API key. You can find your API key in your account's Developers Tools panel.

The Run model

The Run model contains all the information about the execution of a Dust app.

Properties

Name
run_id
Type
string
Description
Unique identifier for the run.
Name
created
Type
integer
Description
Unix epoch in ms marking the creation of the run.
Name
run_type
Type
string
Description
One of local (run created from the Dust interface during design phase) or deployed (run created by API).
Name
config
Type
object
Description
An object representing the configuration of the run (see the Block documentation for details on the difference between block specification and configuration). Keys are block names and values are objects containing the configuration used for the associated block as part of this run.
Name
status
Type
object
Description
An object representing the status of the run. It contains a field run showing the global status of the run (one of running, errored or succeeded) and a blocks field which is an array providing detailed status for each block of the app. Each block status object exposes block_type, name, status (one of running, errored or succeeded), success_count and error_count. If the status of the block is not running then the sum of success_count and error_count will be equal to the number of times the block has been executed (number of inputs and posssibly more if part of a map reduce pair).
Name
traces
Type
[]((block_type, block_name), [][]block_execution)
Description
An array tracing the execution of each block. Each element of the top-level array is an array whose first element is a tuple with the block type and block name. The second element is an array of arrays of block executions. The first dimension is the input dimension (one element per input passed as argument to the run) the second dimension is the map dimension (only one element if outside of a map reduce block, otherwise one element per iteration of the map block). The block execution is an object with fields value and error. At most one is set. If value is set, it contains the output of the block execution. If error is set, it contains the error returned by the block.
Name
specification_hash
Type
string
Description
The hash of the specification used to create the run.
Name
results
Type
[][]block_execution
Description
Only set if the run status is succeeded. The block executions of the last block of the app (see above for the structure of the array of array of block executions).

POST/v1/w/:workspace_id/apps/:app_id/runs

Create a Run

This endpoint allows you to execute a Dust app by API by creating a new Run object. To get a prefilled and ready-to-use curl command, click Deploy from your app specification view. You can only run your own apps. If you want to run someone else's app, simply clone it and run the cloned version from your account.

URL attributes

Name
workspace_id
Type
string
Description
The ID of the app's workspace (can be found in the app's URL)
Name
app_id
Type
string
Description
The ID of the Dust app you want to execute.

JSON body attributes

Attributes are passed as a JSON object in the request body.

Name
specification_hash
Type
string
Description
The hash of the specification to use. If you change your app specifiction, make sure to update the hash. This guarantees that you won't break an existing API integration by iterating on your app design.
Name
config
Type
object
Description
The configuration of the app to use. See the Block documentation for more details on the difference between block specification and configuration. Keys are block names and values are objects containing the configuration used for the associated block as part of this run. Each block documentation also contains a list of configurable values.
Name
inputs
Type
[]object
Description
An array of inputs to run your app with, represented as JSON objects.

Optional JSON body attributes

Name
stream
Type
bool
Description
Whether to stream the run as Server-Sent Events (SSE). If use_stream is set in the model config, this will also stream the tokens as they get emitted by the model (if supported by the provider). If set to true the blocking parameter is ignored.
Name
blocking
Type
bool
Description
Whether to block the API call until the app has finished running. If set to false (default), the API call will return directly with the initial status of the Run. You can then poll the Run using the GET request below.

Request

POST

/v1/w/:workspace_id/apps/:app_id/runs

curl https://dust.tt/api/v1/w/3e26b0e764/apps/cc77ea22f8/runs \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "specification_hash": "ac26d350409be...bebb25013f",
    "config": {
      "MODEL":{
        "provider_id": "openai",
        "model_id": "text-davinci-003",
        "use_cache": false,
        "use_stream": false
      }
    },
    "stream": false,
    "blocking": true,
    "inputs": [
      {"question": "What is 5*7?"}
    ]
  }'

Response

{
  "run": {
    "run_id": "5be2f49d42d19...097cd573",
    "created": 1675247061982,
    "run_type": "deploy",
    "config": {
      "blocks": {
        "MODEL":{
          "provider_id": "openai",
          "model_id": "text-davinci-003",
          "use_cache": false,
          "use_stream": false
        }
      }
    },
    "status":{
      "run": "succeeded",
      "blocks": [
        {
          "block_type": "llm",
          "name": "MODEL",
          "status": "succeeded",
          "success_count": 1,
          "error_count": 0
        }
      ]
    },
    "traces": [
      [
        ["input","INPUT"],
        [[{"value": {...}, "error": null}]]
      ],
      [
        ["llm","MODEL"],
        [[{"value": {...}, "error": null}]]
      ]
    ],
    "specification_hash": "ac26d350409be...bebb25013f",
    "results": [[{"value": {...}, "error": null}]]
  }
}

GET/v1/w/:workspace_id/apps/:app_id/runs/:run_id

Retrieve a Run

This endpoint allows you to retrieve a Run. It can be used to poll the Run status as it is executing if you did not set the blocking or stream paramteters to true.

URL attributes

Name
workspace_id
Type
string
Description
The ID of the app's workspace (can be found in the app's URL)
Name
app_id
Type
string
Description
The ID of the Dust app you want to execute.
Name
run_id
Type
string
Description
The ID of the Run object as returned by the POST request above.

Request

GET

/v1/w/:workspace_id/apps/:app_id/runs/:run_id

curl https://dust.tt/api/v1/w/3e26b0e764/apps/cc77ea22f8/runs/5be2f49d42d19...097cd573 \
  -H "Authorization: Bearer sk-..." \

Response

{
  "run": {
    "run_id": "5be2f49d42d19...097cd573",
    "created": 1675247061982,
    "run_type": "deploy",
    "config": {
      "blocks": {
        "MODEL":{
          "provider_id": "openai",
          "model_id": "text-davinci-003",
          "use_cache": false,
          "use_stream": false
        }
      }
    },
    "status":{
      "run": "succeeded",
      "blocks": [
        {
          "block_type": "llm",
          "name": "MODEL",
          "status": "succeeded",
          "success_count": 1,
          "error_count": 0
        }
      ]
    },
    "traces": [
      [
        ["input","INPUT"],
        [[{"value": {...}, "error": null}]]
      ],
      [
        ["llm","MODEL"],
        [[{"value": {...}, "error": null}]]
      ]
    ],
    "specification_hash": "ac26d350409be...bebb25013f",
    "results": [[{"value": {...}, "error": null}]]
  }
}