> ## Documentation Index > Fetch the complete documentation index at: https://docs.re-factor.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Run State > Retrieve the current state and results of a run 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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 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 ## OpenAPI ````yaml GET /v1/run/{id} openapi: 3.1.0 info: title: re-factor API Reference version: 1.0.0 description: API specification for re-factor system based on schema definitions servers: [] security: - BearerAuth: [] paths: /v1/run/{id}: get: summary: Get the state of a run parameters: - name: id in: path required: true schema: type: string description: The ID of the run to fetch responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RunState' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalError' components: schemas: RunState: type: object required: - id - account_id - status - created_at properties: id: type: string format: uuid description: Unique identifier for the run account_id: type: string description: ID of the account that owns this run parent_run_id: type: string format: uuid nullable: true description: ID of the parent run if this is a child run runnable_id: type: string format: uuid nullable: true description: ID of the runnable that was executed telemetry_span_id: type: string nullable: true description: Telemetry span ID for tracing experiment_id: type: string format: uuid nullable: true description: ID of the experiment this run belongs to experiment_candidate_id: type: string nullable: true description: ID of the experiment candidate this run represents status: type: string enum: - running - completed - failed - cancelled - timeout - waiting description: Current status of the run state: type: object nullable: true additionalProperties: true description: Current state of the run created_by: type: string nullable: true description: ID of the user who created the run created_at: type: string format: date-time description: When the run was created completed_at: type: string format: date-time nullable: true description: >- When the run completed (for completed, failed, cancelled, or timeout status) total_input_tokens: type: integer nullable: true description: Total number of input tokens used total_cached_tokens: type: integer nullable: true description: Total number of cached tokens used total_output_tokens: type: integer nullable: true description: Total number of output tokens generated total_token_cost_usd: type: number nullable: true description: Total cost of the run in USD failed_at: type: string format: date-time nullable: true description: When the run failed (for failed status) result: $ref: '#/components/schemas/RunResult' nullable: true description: >- 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: type: object nullable: true additionalProperties: true description: Additional metadata about the run RunResult: type: object properties: id: type: string description: >- The id of the run. This can be used to query the status of the run or fetch its output. outputs: type: object additionalProperties: true description: >- The outputs of the run. This is a map of output names, defined within the runnable configuration, to output values. metadata: type: object additionalProperties: true description: The metadata of the run. This is a map of arbitrary keys to values. usage: type: array items: $ref: '#/components/schemas/ModelUsage' error: type: object description: The error that occurred during the run, if any. properties: message: type: string description: The error message code: type: string description: The error code required: - message required: - id ModelUsage: type: object properties: provider: type: string description: The provider of the model model: type: string description: The name of the model cached_tokens: type: integer description: The number of cached tokens used prompt_tokens: type: integer description: The number of prompt tokens used completion_tokens: type: integer description: The number of completion tokens used required: - provider - model - cached_tokens - prompt_tokens - completion_tokens responses: UnauthorizedError: description: Unauthorized content: application/json: schema: type: object properties: error: type: string ForbiddenError: description: Forbidden content: application/json: schema: type: object properties: error: type: string NotFoundError: description: Not Found content: application/json: schema: type: object properties: error: type: string InternalError: description: Internal Server Error content: application/json: schema: type: object properties: error: type: string securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````