Retrieve a Run
Read an original Run and its currently deliverable result without another purchase.
View as MarkdownEndpoint
Retrieval returns HTTP 200 with the current Run, including pending states. Use status and pollAfterMs to decide when to read again; HTTP 200 alone does not mean execution succeeded.
Read result.output only when result.status is available. Available results include output, which may be null, and deliveryUntil; file-capable tools may also return artifacts. Expired and unavailable results do not contain deliverable output.
billing carries heldMicros, chargedMicros and refundedMicros. A timeout, cancellation request or expired file is not enough to infer the final charge.
GET /v1/runs/{runId}Parameters
| Name | Location | Type | Required | Constraints |
|---|---|---|---|---|
| runId | path | string | Required | — |
Request example
Set PURRKEY_API_KEY in your trusted server or terminal environment. Replace any angle-bracket placeholders with values from your own inspection or Run.
curl --fail-with-body --request GET 'https://api.purrkey.app/v1/runs/<runId>' \
-H "Authorization: Bearer $PURRKEY_API_KEY"Successful response
Success HTTP status: 200. Top-level response fields are listed below. Conditional and nested requirements are defined in the downloadable OpenAPI contract.
| Field | Type | Required | Constraints |
|---|---|---|---|
| runId | string | Required | — |
| toolId | string | Required | — |
| toolRevision | string | Required | — |
| toolName | string | Optional / conditional | — |
| status | string | Required | QUEUED | SUBMITTING | RUNNING | WAITING_PROVIDER | SUCCEEDED | FAILED | CANCELED | TIMED_OUT | UNKNOWN |
| billing | object | Required | — |
| createdAt | string | Required | date-time |
| updatedAt | string | Required | date-time |
| cancelRequestedAt | string | Optional / conditional | date-time |
| payment | object | Optional / conditional | — |
| input | JSON value | Optional / conditional | — |
| result | object | Required | — |
| error | object | Optional / conditional | — |
| pollAfterMs | integer | Optional / conditional | int32; Minimum: 0 |