GET
/
v1
/
run
/
{id}
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "account_id": "<string>",
  "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>",
  "status": "running",
  "state": {},
  "created_by": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "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

200
application/json

OK

The response is of type object.