---
title: "Look up a transaction by rid, GET /ext/transaction/{rid}"
description: "Retrieve the cached response for a previously idempotency-keyed write, so you can safely reconcile after a network failure."
---

# GET /ext/transaction/{rid}

`/ext/transaction/{rid}` is the reconciliation endpoint for the OneStream flavor. Every `POST` in this API accepts an `rid` in its body and, on success, stores the response for at least 24 hours. If the original response never reached your integration (timeout, dropped connection, worker crash, redeploy in the middle of the request), you can call this endpoint with the same `rid` before deciding whether to retry. A 200 tells you the write succeeded and hands you the original response. A 404 tells you the write never reached the panel and it is safe to retry with the same `rid`.

The endpoint does not exist on the underlying v1 API. It is served locally by the OneStream dialect, which looks the `rid` up in the panel's idempotency store, scopes the lookup to the calling key, and returns either the cached response or a uniform 404. Do not build workflows around it, but do call it in your retry code before any repeat `POST` whose result you did not observe.

## Endpoint

`GET https://<your-panel-domain>/panel-api/onestream/ext/transaction/{rid}`

The `{rid}` path segment is the exact string you sent in the body of the original write, URL-encoded. Allowed characters are unreserved URL characters: letters, digits, and `.`, `_`, `~`, `-`. A request whose `{rid}` contains anything else returns a uniform 404 without touching the idempotency store.

## Authentication

Send the API key in `X-Api-Key`, `X-Auth-User`, or `Authorization: Bearer`. See the [OneStream overview](/docs/?page=os-ref-overview#base-url-and-authentication).

## Required scope

None. Any authenticated key can look up transactions **that it created**. The lookup is scoped to the caller's key: an `rid` created by another key is indistinguishable from one that does not exist. Both return 404 with `{"error": "Not Found"}`.

## Path parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `rid` | string | The exact receipt identifier you sent in the body of the write. URL-encode it if it contains reserved characters. |

## Response

Two shapes, on two status codes.

### Found (HTTP 200)

The cached transaction wraps the original response body under a `response` key. The wrapper carries the `rid` echoed back, a `transaction_status` string, and the original HTTP status the write returned.

```json
{
  "rid": "onestream-idem-1",
  "transaction_status": "success",
  "http_status": 201,
  "response": {
    "line_id": "550e8400-e29b-41d4-a716-446655440000",
    "expire_at": "2026-09-08T16:39:45+00:00",
    "transaction_amount": 100,
    "rid": "onestream-idem-1"
  }
}
```

| Field | Type | Description |
| ----- | ---- | ----------- |
| `rid` | string | The receipt identifier echoed from the request. |
| `transaction_status` | string | Fixed value `"success"`. The endpoint only returns 200 when a stored transaction exists; failures are not cached and are not visible here. |
| `http_status` | int | HTTP status the original write returned. |
| `response` | object or null | The parsed JSON body of the original write. `null` when the stored body was not valid JSON (never happens for writes this API produces). |

### Not found (HTTP 404)

```json
{"error": "Not Found"}
```

Returned in every one of these situations, deliberately indistinguishable:

- No transaction with that `rid` exists for the calling key.
- The `rid` exists but was created by a different key on this panel.
- The `rid` path segment contains characters outside the allowed set.
- The request did not present a valid API key.

The lack of distinction is deliberate. If the endpoint told you the difference between "your rid does not exist" and "someone else's rid does", it would let a caller enumerate other integrators' transaction identifiers.

## Recovery workflow

The standard shape of a safe retry loop for any `POST` in this API is:

1. Pick a stable `rid` per business operation (an invoice number, a webhook event id).
2. Send the `POST` with `rid` in the body.
3. If you see the response, you are done. Store the response.
4. If the connection timed out or dropped before you saw the response, call `GET /ext/transaction/{rid}` before doing anything else.
5. If the lookup returns 200, treat the write as complete and use the returned `response` as if the original `POST` had returned it.
6. If the lookup returns 404, the write never reached the panel. Retry the `POST` with the same `rid`. The panel will process it exactly once, and any subsequent lookup will return the response.

## Examples

### cURL

```bash
curl -H "X-Api-Key: <your-api-key>" \
     "https://<your-panel-domain>/panel-api/onestream/ext/transaction/onestream-idem-1"
```

### PHP raw

```php
$rid = 'onestream-idem-1';
$url = 'https://<your-panel-domain>/panel-api/onestream/ext/transaction/' . rawurlencode($rid);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-Api-Key: <your-api-key>']);
$body = json_decode(curl_exec($ch), true);
$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http === 200) {
    echo 'original http_status: ' . $body['http_status'] . PHP_EOL;
    print_r($body['response']);
} elseif ($http === 404) {
    echo "not seen, safe to retry with the same rid\n";
}
```

### Python raw

```python
import requests
from urllib.parse import quote

rid = "onestream-idem-1"
url = (
    "https://<your-panel-domain>/panel-api/onestream/ext/transaction/"
    + quote(rid, safe="")
)
r = requests.get(url, headers={"X-Api-Key": "<your-api-key>"}, timeout=30)

if r.status_code == 200:
    payload = r.json()
    print("original http_status:", payload["http_status"])
    print(payload["response"])
elif r.status_code == 404:
    print("not seen, safe to retry with the same rid")
```

## Errors

| HTTP | Error slug | When it happens | How to fix |
| ---- | ---------- | --------------- | ---------- |
| 404 | `not_found` | The `rid` was not created by this key, does not exist, contains invalid characters, or the request presented no valid API key. | Retry the original `POST` with the same `rid` if you never observed its response. Verify you are calling with the same key that made the original write. |
| 429 | `rate_limited` | The per-key or per-IP rate limit was hit. Response carries `Retry-After` and `X-RateLimit-*` headers. | Back off for the number of seconds in `Retry-After`. |
| 403 | `api_disabled` | An admin has turned the Panel API off for this panel. | Ask the admin to re-enable it. |

## See also

- [OneStream overview, idempotency section](/docs/?page=os-ref-overview#idempotency-by-rid)
- [Rate limits and Idempotency](/docs/?page=panel-api-rate-limits-idempotency) for the full retry contract.
- [OneStream compatibility notes, transaction lookup](/docs/?page=panel-api-onestream-compatibility#idempotency-via-rid)