curl --request GET \
--url https://api.example.com/v1/run/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/v1/run/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/v1/run/{id}', 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/v1/run/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/run/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/v1/run/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/run/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"account_id": "<string>",
"status": "running",
"created_at": "2023-11-07T05:31:56Z",
"parent_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"runnable_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"telemetry_span_id": "<string>",
"experiment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"experiment_candidate_id": "<string>",
"state": {},
"created_by": "<string>",
"completed_at": "2023-11-07T05:31:56Z",
"total_input_tokens": 123,
"total_cached_tokens": 123,
"total_output_tokens": 123,
"total_token_cost_usd": 123,
"failed_at": "2023-11-07T05:31:56Z",
"result": {
"id": "<string>",
"outputs": {},
"metadata": {},
"usage": [
{
"provider": "<string>",
"model": "<string>",
"cached_tokens": 123,
"prompt_tokens": 123,
"completion_tokens": 123
}
],
"error": {
"message": "<string>",
"code": "<string>"
}
},
"metadata": {}
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}Get Run State
Retrieve the current state and results of a run
curl --request GET \
--url https://api.example.com/v1/run/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/v1/run/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/v1/run/{id}', 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/v1/run/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/run/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/v1/run/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/run/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"account_id": "<string>",
"status": "running",
"created_at": "2023-11-07T05:31:56Z",
"parent_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"runnable_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"telemetry_span_id": "<string>",
"experiment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"experiment_candidate_id": "<string>",
"state": {},
"created_by": "<string>",
"completed_at": "2023-11-07T05:31:56Z",
"total_input_tokens": 123,
"total_cached_tokens": 123,
"total_output_tokens": 123,
"total_token_cost_usd": 123,
"failed_at": "2023-11-07T05:31:56Z",
"result": {
"id": "<string>",
"outputs": {},
"metadata": {},
"usage": [
{
"provider": "<string>",
"model": "<string>",
"cached_tokens": 123,
"prompt_tokens": 123,
"completion_tokens": 123
}
],
"error": {
"message": "<string>",
"code": "<string>"
}
},
"metadata": {}
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}Run Statuses
A run can be in one of the following statuses:running: The run is currently executingcompleted: The run has successfully completedfailed: The run encountered an error during executioncancelled: The run was cancelled by the user or systemtimeout: The run exceeded its maximum allowed execution timewaiting: The run is waiting for user input before it can continue execution
Timing Information
The response includes several timestamps to track the run’s lifecycle:created_at: When the run was first createdcompleted_at: When execution finished (for completed, failed, cancelled, or timeout status)failed_at: When the run failed (for failed status)
Token Usage
For runs that involve LLM interactions:result.prompt_tokens: Number of tokens in the inputresult.cached_tokens: Number of tokens retrieved from cache (typically billed at a lower rate)result.completion_tokens: Number of tokens generated in the output
Run Hierarchy and Context
parent_run_id: ID of the parent run if this is part of a larger workflowrunnable_id: ID of the runnable (prompt, agent, or flow) that was executedexperiment_id: ID of the experiment this run belongs to (if any)experiment_candidate_id: ID of the experiment candidate this run represents (if any)telemetry_span_id: Span ID for distributed tracing
Examples
Running Run
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"account_id": "acc_01HGK2V8N5XJVB8Q2Z3R4Y5T6M",
"status": "running",
"runnable_id": "456e4567-e89b-12d3-a456-426614174000",
"state": {
"current_step": "processing_input",
"progress": 0.25
},
"created_by": "user_01HGK2V8N5XJVB8Q2Z3R4Y5T6M",
"created_at": "2025-01-12T13:17:30-06:00"
}
Completed Run
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"account_id": "acc_01HGK2V8N5XJVB8Q2Z3R4Y5T6M",
"status": "completed",
"runnable_id": "456e4567-e89b-12d3-a456-426614174000",
"result": {
"outputs": {
"weather_description": "The weather is sunny with a high of 75°F"
},
"usage": {
"prompt_tokens": 150,
"cached_tokens": 50,
"completion_tokens": 400
}
},
"created_by": "user_01HGK2V8N5XJVB8Q2Z3R4Y5T6M",
"created_at": "2025-01-12T13:17:30-06:00",
"completed_at": "2025-01-12T13:17:35-06:00"
}
Failed Run
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"account_id": "acc_01HGK2V8N5XJVB8Q2Z3R4Y5T6M",
"status": "failed",
"runnable_id": "456e4567-e89b-12d3-a456-426614174000",
"result": {
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "OpenAI API rate limit exceeded"
}
},
"created_by": "user_01HGK2V8N5XJVB8Q2Z3R4Y5T6M",
"created_at": "2025-01-12T13:17:30-06:00",
"failed_at": "2025-01-12T13:17:32-06:00"
}
Experiment Run
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"account_id": "acc_01HGK2V8N5XJVB8Q2Z3R4Y5T6M",
"status": "completed",
"runnable_id": "456e4567-e89b-12d3-a456-426614174000",
"experiment_id": "789e4567-e89b-12d3-a456-426614174000",
"experiment_candidate_id": "candidate_01",
"result": {
"outputs": {
"weather_description": "The weather is sunny with a high of 75°F"
},
"usage": {
"prompt_tokens": 150,
"cached_tokens": 50,
"completion_tokens": 400
}
},
"created_by": "user_01HGK2V8N5XJVB8Q2Z3R4Y5T6M",
"created_at": "2025-01-12T13:17:30-06:00",
"completed_at": "2025-01-12T13:17:35-06:00",
"metadata": {
"experiment_group": "weather_response_optimization",
"model_version": "gpt-4o"
}
}
Common Error Codes
| Error Code | Description |
|---|---|
INTERNAL_ERROR | An unexpected error occurred in the system |
INVALID_INPUT | The provided input was invalid or malformed |
RESOURCE_NOT_FOUND | A required resource was not found |
TIMEOUT | The run exceeded its maximum execution time |
RATE_LIMIT_EXCEEDED | Too many requests were made in a short period |
AUTHORIZATION_ERROR | The request lacks valid authentication credentials |
Usage Tips
-
Polling Interval: When polling for run status, we recommend:
- Start with 1-second intervals for the first 5 seconds
- Then increase to 5-second intervals until 30 seconds
- Finally use 30-second intervals until completion
-
Timeouts: Different run types have different timeout limits:
- Prompts: 30 seconds
- Agents: 5 minutes
- Flows: 15 minutes
-
Error Handling: Always check both the
statusfield and presence oferror/resultfields to determine the run’s outcome
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The ID of the run to fetch
Response
OK
Unique identifier for the run
ID of the account that owns this run
Current status of the run
running, completed, failed, cancelled, timeout, waiting When the run was created
ID of the parent run if this is a child run
ID of the runnable that was executed
Telemetry span ID for tracing
ID of the experiment this run belongs to
ID of the experiment candidate this run represents
Current state of the run
ID of the user who created the run
When the run completed (for completed, failed, cancelled, or timeout status)
Total number of input tokens used
Total number of cached tokens used
Total number of output tokens generated
Total cost of the run in USD
When the run failed (for failed status)
Result of the run. If the run has not yet completed, this will be partially populated and is subject to change over time. This may be null if the run has yet to generate any output.
Show child attributes
Show child attributes
Additional metadata about the run

