> ## Documentation Index > Fetch the complete documentation index at: https://docs.rafflesia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Stream run queue status > Streams the same versioned status shape as text/event-stream and closes after completed, failed, or canceled. since_version resumes after a previously observed version. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/runs/{run_id}/status/stream openapi: 3.1.0 info: description: >- Deterministic biological evidence primitives with typed resource, list, and error responses. Each operation documents its own response shape, provenance, warnings, and transport headers. title: Rafflesia API version: 0.1.0 servers: - description: Production url: https://api.rafflesia.ai security: - bearerAuth: [] paths: /v1/runs/{run_id}/status/stream: get: tags: - Runs summary: Stream run queue status description: >- Streams the same versioned status shape as text/event-stream and closes after completed, failed, or canceled. since_version resumes after a previously observed version. operationId: runs.status.stream parameters: - in: path name: run_id required: true schema: pattern: ^run_[0-9a-f]{24}$ type: string - description: Include retained execution logs in each status event. explode: false in: query name: logs schema: description: Include retained execution logs in each status event. type: boolean - description: Resume after a previously observed status version. explode: false in: query name: since_version schema: description: Resume after a previously observed status version. format: int64 minimum: 0 type: integer responses: '200': content: text/event-stream: schema: $ref: '#/components/schemas/RunStatus' description: OK headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '400': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Bad Request headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '401': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Unauthorized headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '402': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Payment Required headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Forbidden headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '404': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Not Found headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '405': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Method Not Allowed headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '406': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Not Acceptable headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '408': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Request Timeout headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '410': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Gone headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Unprocessable Entity headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '429': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Too Many Requests headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string RateLimit: description: Remaining capacity and reset interval for this refusal. schema: type: string RateLimit-Policy: description: Effective request, queue, or execution-capacity policy. schema: type: string Retry-After: description: Whole seconds to wait before retrying a transient error. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '499': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Client Closed Request headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '500': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Internal Server Error headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '502': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Bad Gateway headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string Retry-After: description: Whole seconds to wait before retrying a transient error. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '503': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Service Unavailable headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string Retry-After: description: Whole seconds to wait before retrying a transient error. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string '504': content: application/json: schema: $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData' description: Gateway Timeout headers: Rafflesia-Contract-Digest: description: Digest of the full API contract used for this response. schema: type: string Rafflesia-Error-Type: description: Stable machine-readable error code, identical to error.code. schema: type: string Rafflesia-Request-Timeout-Type: description: >- Set to user when the caller-supplied start deadline caused this response. schema: enum: - user type: string Rafflesia-Retryable: description: Whether retrying the identical pinned request may succeed. schema: enum: - 'true' - 'false' type: string Rafflesia-Version: description: API contract version used for this response. schema: type: string Retry-After: description: Whole seconds to wait before retrying a transient error. schema: type: string X-Rafflesia-Billable-Units: description: >- Frozen units billed when execution produced a chargeable terminal result. schema: type: string X-Rafflesia-Runner-Hints: description: Best-effort affinity hint suitable for a later related request. schema: type: string X-Rafflesia-Served-From: description: Execution worker identifier that handled the latest attempt. schema: type: string X-Request-ID: description: Request identifier for support and log correlation. schema: type: string x-codeSamples: - lang: bash source: | curl --request GET \ --url "https://api.rafflesia.ai/v1/runs/{run_id}/status/stream" \ --header "Authorization: Bearer $RAFFLESIA_API_KEY" components: schemas: RunStatus: additionalProperties: false properties: attempt: format: int64 minimum: 0 type: integer cancel_url: type: string canceled_at: format: date-time type: string completed_at: format: date-time type: string created_at: format: date-time type: string error: $ref: '#/components/schemas/ExecutionAPIError' id: pattern: ^run_[0-9a-f]{24}$ type: string logs: items: $ref: '#/components/schemas/JobEvent' type: - array - 'null' max_retries: format: int64 minimum: 0 type: integer metrics_ms: additionalProperties: format: int64 type: integer type: object object: enum: - run_status type: string progress: $ref: '#/components/schemas/RunProgress' queue: $ref: '#/components/schemas/RunQueue' result_url: type: string runner_hint: type: string served_from: type: string start_deadline_at: format: date-time type: string started_at: format: date-time type: string status: enum: - queued - in_progress - completed - failed - canceled type: string status_stream_url: type: string status_url: type: string version: format: int64 minimum: 1 type: integer required: - id - object - status - attempt - max_retries - version - result_url - status_url - status_stream_url - cancel_url - created_at type: object ExecutionEnvelopeExecutionErrorData: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - >- https://example.com/schemas/ExecutionEnvelopeExecutionErrorData.json format: uri readOnly: true type: string data: $ref: '#/components/schemas/ExecutionErrorData' description: Operation result data. Absent when the operation did not succeed. error: $ref: '#/components/schemas/ExecutionAPIError' description: Structured execution error information. evidence: $ref: '#/components/schemas/EvidenceSummary' description: Mechanical evidence summary for agent inspection and chaining. ok: description: Whether the operation succeeded. type: boolean provenance: $ref: '#/components/schemas/Provenance' description: Execution provenance. warnings: description: Non-fatal warnings. items: $ref: '#/components/schemas/Warning' type: - array - 'null' required: - ok - warnings - provenance type: object ExecutionAPIError: additionalProperties: false properties: code: description: Stable specific error code. Branch on this value instead of message. type: string details: additionalProperties: {} description: Additional structured error details retained for compatibility. type: object doc_url: description: Stable documentation URL for this error code. type: string errors: description: >- One or more exact validation or execution failures. Machine logic should use type, loc, and ctx; msg is for people. items: $ref: '#/components/schemas/APIErrorDetail' type: array is_retryable: description: >- Whether retrying the identical pinned request may succeed without changing its input. type: boolean message: description: Human-readable actionable explanation. Do not parse this value. type: string param: description: Request field responsible for the error when known. type: string request_id: description: Request identifier to provide when reporting this occurrence. type: string type: description: Stable coarse error category. enum: - invalid_request_error - resource_missing - resource_expired - conflict_error - rate_limit_error - authentication_error - permission_error - billing_error - api_error type: string required: - type - code - message - doc_url - is_retryable type: object JobEvent: additionalProperties: false properties: attempt: format: int64 type: integer created_at: type: string details: additionalProperties: type: string type: object message: type: string sequence: format: int64 type: integer type: type: string worker_id: type: string required: - sequence - type - created_at type: object RunProgress: additionalProperties: false properties: current: format: int64 minimum: 0 type: integer stage: type: string total: format: int64 minimum: 0 type: integer unit: type: string updated_at: format: date-time type: string required: - stage - updated_at type: object RunQueue: additionalProperties: false properties: is_position_estimated: type: boolean position: format: int64 minimum: 0 type: integer priority: enum: - normal - low type: string queued_at: format: date-time type: string scope: enum: - organization - endpoint - deployment type: string required: - position - is_position_estimated - scope - priority - queued_at type: object ExecutionErrorData: additionalProperties: false type: object EvidenceSummary: additionalProperties: false properties: duration_ms: description: >- Primary elapsed duration in milliseconds when the response exposes one. format: int64 type: integer input_refs: description: >- Input references detected from request fields such as object_id, structure_id, target_id, and sequence_id. items: type: string type: - array - 'null' object_refs: description: Object ids or object refs visible in the response/provenance. items: type: string type: - array - 'null' output_refs: description: Output references detected from response data and generated objects. items: type: string type: - array - 'null' row_count: description: >- Primary row count or returned row count when the response exposes one. format: int64 type: integer warnings_count: description: Number of non-fatal warnings in the envelope. format: int64 type: integer required: - warnings_count type: object Provenance: additionalProperties: false properties: cache_hit: description: Whether cached output was reused. type: boolean created_at: description: UTC timestamp. type: string database_snapshots: description: Database snapshots used. items: $ref: '#/components/schemas/DatabaseSnapshot' type: - array - 'null' generated_object_ids: description: Object ids created by the operation. items: type: string type: - array - 'null' input_hash: description: SHA-256 hash of canonical request input. type: string operation: description: Primitive operation id. type: string parameters_hash: description: SHA-256 hash of parameters. type: string request_id: description: Unique request identifier. type: string server_version: description: Server version. type: string tool_versions: description: Tool versions used. items: $ref: '#/components/schemas/ToolVersion' type: - array - 'null' required: - request_id - operation - created_at - server_version type: object Warning: additionalProperties: false properties: code: description: Stable warning code. type: string details: additionalProperties: {} description: Additional structured warning details. type: object message: description: Human-readable warning message. type: string required: - code - message type: object APIErrorDetail: additionalProperties: false properties: ctx: additionalProperties: {} description: Structured constraint or failure context. type: object input: description: Offending non-sensitive scalar when it is safe and useful to echo. loc: description: >- Path to the failing value, beginning with body, query, path, or header. items: type: string type: array msg: description: Human-readable explanation. Do not parse this value. type: string type: description: Stable machine-readable failure type. type: string url: description: Documentation URL for this failure type. type: string required: - loc - msg - type - url type: object DatabaseSnapshot: additionalProperties: false properties: digest: type: string kind: type: string name: type: string version: type: string required: - name - version type: object ToolVersion: additionalProperties: false properties: name: type: string path: type: string version: type: string required: - name - version type: object securitySchemes: bearerAuth: description: 'A Rafflesia API key, sent as `Authorization: Bearer `.' scheme: bearer type: http ````