Skip to main content
POST
/
runs
Stateless Create Run
curl --request POST \
  --url https://api.example.com/runs \
  --header 'Content-Type: application/json' \
  --data '
{
  "assistant_id": "<string>",
  "input": {},
  "config": {},
  "context": {},
  "checkpoint": {},
  "stream": false,
  "stream_mode": "<string>",
  "on_disconnect": "<string>",
  "multitask_strategy": "<string>",
  "command": {},
  "interrupt_before": "<string>",
  "interrupt_after": "<string>",
  "stream_subgraphs": false,
  "metadata": {}
}
'
import requests

url = "https://api.example.com/runs"

payload = {
"assistant_id": "<string>",
"input": {},
"config": {},
"context": {},
"checkpoint": {},
"stream": False,
"stream_mode": "<string>",
"on_disconnect": "<string>",
"multitask_strategy": "<string>",
"command": {},
"interrupt_before": "<string>",
"interrupt_after": "<string>",
"stream_subgraphs": False,
"metadata": {}
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
assistant_id: '<string>',
input: {},
config: {},
context: {},
checkpoint: {},
stream: false,
stream_mode: '<string>',
on_disconnect: '<string>',
multitask_strategy: '<string>',
command: {},
interrupt_before: '<string>',
interrupt_after: '<string>',
stream_subgraphs: false,
metadata: {}
})
};

fetch('https://api.example.com/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/runs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'assistant_id' => '<string>',
'input' => [

],
'config' => [

],
'context' => [

],
'checkpoint' => [

],
'stream' => false,
'stream_mode' => '<string>',
'on_disconnect' => '<string>',
'multitask_strategy' => '<string>',
'command' => [

],
'interrupt_before' => '<string>',
'interrupt_after' => '<string>',
'stream_subgraphs' => false,
'metadata' => [

]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://api.example.com/runs"

payload := strings.NewReader("{\n \"assistant_id\": \"<string>\",\n \"input\": {},\n \"config\": {},\n \"context\": {},\n \"checkpoint\": {},\n \"stream\": false,\n \"stream_mode\": \"<string>\",\n \"on_disconnect\": \"<string>\",\n \"multitask_strategy\": \"<string>\",\n \"command\": {},\n \"interrupt_before\": \"<string>\",\n \"interrupt_after\": \"<string>\",\n \"stream_subgraphs\": false,\n \"metadata\": {}\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.example.com/runs")
.header("Content-Type", "application/json")
.body("{\n \"assistant_id\": \"<string>\",\n \"input\": {},\n \"config\": {},\n \"context\": {},\n \"checkpoint\": {},\n \"stream\": false,\n \"stream_mode\": \"<string>\",\n \"on_disconnect\": \"<string>\",\n \"multitask_strategy\": \"<string>\",\n \"command\": {},\n \"interrupt_before\": \"<string>\",\n \"interrupt_after\": \"<string>\",\n \"stream_subgraphs\": false,\n \"metadata\": {}\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.example.com/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"assistant_id\": \"<string>\",\n \"input\": {},\n \"config\": {},\n \"context\": {},\n \"checkpoint\": {},\n \"stream\": false,\n \"stream_mode\": \"<string>\",\n \"on_disconnect\": \"<string>\",\n \"multitask_strategy\": \"<string>\",\n \"command\": {},\n \"interrupt_before\": \"<string>\",\n \"interrupt_after\": \"<string>\",\n \"stream_subgraphs\": false,\n \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body
{
  "run_id": "<string>",
  "thread_id": "<string>",
  "assistant_id": "<string>",
  "user_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "status": "pending",
  "input": {},
  "output": {},
  "error_message": "<string>",
  "config": {},
  "context": {}
}
{
"error": "<string>",
"message": "<string>",
"details": {}
}
{
"error": "<string>",
"message": "<string>",
"details": {}
}
{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}

Body

application/json

Request model for creating runs

assistant_id
string
required

Assistant to execute

input
Input · object | null

Input data for the run. Optional when resuming from a checkpoint.

config
Config · object | null

Execution config

context
Context · object | null

Execution context

checkpoint
Checkpoint · object | null

Checkpoint configuration (e.g., {'checkpoint_id': '...', 'checkpoint_ns': ''})

stream
boolean
default:false

Enable streaming response

stream_mode

Requested stream mode(s)

on_disconnect
string | null

Behavior on client disconnect: 'cancel' (default) or 'continue'.

on_completion
enum<string> | null

Behavior after stateless run completes: 'delete' (default) removes the ephemeral thread, 'keep' preserves it.

Available options:
delete,
keep
multitask_strategy
string | null

Strategy for handling concurrent runs on same thread: 'reject', 'interrupt', 'rollback', or 'enqueue'.

command
Command · object | null

Command for resuming interrupted runs with state updates or navigation

interrupt_before

Nodes to interrupt immediately before they get executed. Use '*' for all nodes.

interrupt_after

Nodes to interrupt immediately after they get executed. Use '*' for all nodes.

stream_subgraphs
boolean | null
default:false

Whether to include subgraph events in streaming. When True, includes events from all subgraphs. When False (default when None), excludes subgraph events. Defaults to False for backwards compatibility.

metadata
Metadata · object | null

Request metadata propagated to OTEL trace attributes (langfuse.trace.metadata.<key>). Keys must match [A-Za-z0-9_-]{1,64}. Values must be primitive (str, int, float, bool); string values are capped at 512 characters. Maximum 32 keys. Use this for filterable attributes (tenant, feature flag, environment, sub-agent type) rather than payload data.

Response

Successful Response

Run entity model

Status values: pending, running, error, success, timeout, interrupted

run_id
string
required

Unique identifier for the run.

thread_id
string
required

Thread this run belongs to.

assistant_id
string
required

Assistant that is executing this run.

user_id
string
required

Identifier of the user who owns this run.

created_at
string<date-time>
required

Timestamp when the run was created.

updated_at
string<date-time>
required

Timestamp when the run was last updated.

status
string
default:pending

Current run status: pending, running, error, success, timeout, or interrupted.

input
Input · object | null

Input data provided to the run. None for checkpoint-only resume.

output
Output · object | null

Final output produced by the run, or null if not yet complete.

error_message
string | null

Error message if the run failed.

config
Config · object | null

Configuration passed to the graph at runtime.

context
Context · object | null

Context variables available during execution.