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 API keys 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) ordeployed
(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 ablocks
field which is an array providing detailed status for each block of the app. Each block status object exposesblock_type
,name
,status
(one of running, errored or succeeded),success_count
anderror_count
. If the status of the block is not running then the sum ofsuccess_count
anderror_count
will be equal to the number of times the block has been executed (number of inputs and posssibly more if part of amap
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 themap
block). The block execution is an object with fieldsvalue
anderror
. At most one is set. Ifvalue
is set, it contains the output of the block execution. Iferror
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).
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
user
- Type
- string
- Description
Your Dust username.
- 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 theblocking
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
curl https://dust.tt/api/v1/apps/spolu/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}]]
}
}
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
user
- Type
- string
- Description
Your Dust username.
- 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
curl https://dust.tt/api/v1/apps/spolu/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}]]
}
}