Skip to main content
GET
/
v1
/
run
/
{id}
Get the state of a run
curl --request GET \
  --url https://api.example.com/v1/run/{id} \
  --header 'Authorization: Bearer <token>'
{
  "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": {}
}
This endpoint allows you to check the status of any run (prompt, agent, or flow). The response includes the current status, timing information, token usage, and state data.

​
Run Statuses

A run can be in one of the following statuses:
  • running: The run is currently executing
  • completed: The run has successfully completed
  • failed: The run encountered an error during execution
  • cancelled: The run was cancelled by the user or system
  • timeout: The run exceeded its maximum allowed execution time
  • waiting: 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 created
  • completed_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 input
  • result.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 workflow
  • runnable_id: ID of the runnable (prompt, agent, or flow) that was executed
  • experiment_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 CodeDescription
INTERNAL_ERRORAn unexpected error occurred in the system
INVALID_INPUTThe provided input was invalid or malformed
RESOURCE_NOT_FOUNDA required resource was not found
TIMEOUTThe run exceeded its maximum execution time
RATE_LIMIT_EXCEEDEDToo many requests were made in a short period
AUTHORIZATION_ERRORThe request lacks valid authentication credentials

​
Usage Tips

  1. 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
  2. Timeouts: Different run types have different timeout limits:
    • Prompts: 30 seconds
    • Agents: 5 minutes
    • Flows: 15 minutes
  3. Error Handling: Always check both the status field and presence of error/result fields to determine the run’s outcome

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string
required

The ID of the run to fetch

Response

OK

​
id
string<uuid>
required

Unique identifier for the run

​
account_id
string
required

ID of the account that owns this run

​
status
enum<string>
required

Current status of the run

Available options:
running,
completed,
failed,
cancelled,
timeout,
waiting
​
created_at
string<date-time>
required

When the run was created

​
parent_run_id
string<uuid> | null

ID of the parent run if this is a child run

​
runnable_id
string<uuid> | null

ID of the runnable that was executed

​
telemetry_span_id
string | null

Telemetry span ID for tracing

​
experiment_id
string<uuid> | null

ID of the experiment this run belongs to

​
experiment_candidate_id
string | null

ID of the experiment candidate this run represents

​
state
object

Current state of the run

​
created_by
string | null

ID of the user who created the run

​
completed_at
string<date-time> | null

When the run completed (for completed, failed, cancelled, or timeout status)

​
total_input_tokens
integer | null

Total number of input tokens used

​
total_cached_tokens
integer | null

Total number of cached tokens used

​
total_output_tokens
integer | null

Total number of output tokens generated

​
total_token_cost_usd
number | null

Total cost of the run in USD

​
failed_at
string<date-time> | null

When the run failed (for failed status)

​
result
object

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.

​
metadata
object

Additional metadata about the run