# Retrieve a Run

Read an original Run and its currently deliverable result without another purchase.

## Endpoint

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 |

## Errors and related reading

- [Error handling](/docs/guides/errors): Read requestId, business codes and safe retry behavior.
- [Download OpenAPI](/docs/openapi.yaml): The complete HTTP contract, version 0.4.3.