GET /runs and GET /runs/:runId
Your run history and the full report of any run, read with an API key. Free and read-only: runs are created by
POST /explainandPOST /explain/async, never here.
URL: https://mpp.oculr.xyz/runs and https://mpp.oculr.xyz/runs/:runId
Auth: an API key, sent as Authorization: Bearer oc_live_.... A key for a Google account sees that account's runs, the same list as My reports in the web app. An organisation key sees its organisation's runs. Neither route ever charges.
GET /runs
Your runs, newest first.
Parameters
| Param | Type | Required | Description |
|---|---|---|---|
limit | integer (query) | no | Runs per page, 1 to 50. Default 20. Values outside the range are clamped. |
offset | integer (query) | no | How many of the newest runs to skip. Default 0. |
200 OK
{
"runs": [
{
"id": 4815162342,
"txHash": "0x5453629f95d08b28ef2c5b0fc72e9330d02aa6740703defbaa6b84de470adfe1",
"chain": "base-mainnet",
"chainId": 8453,
"createdAt": "2026-10-09T18:11:52.345Z",
"status": "complete",
"priceUsd": 1.33,
"free": false,
"txType": "lending",
"keyId": "k_3f9a",
"summary": "Borrow of USDC against cbETH collateral on Moonwell...",
"links": { "self": "/runs/4815162342" }
}
],
"limit": 20,
"offset": 0,
"nextOffset": null
}| Field | Type | Notes |
|---|---|---|
id | integer | null | The run id. Pass it to GET /runs/:runId. null for runs made before run ids were introduced on 2026-10-09; those are listed but cannot be opened here. |
txHash | string | The transaction that was analysed. |
chain | string | null | Chain slug the transaction was found on. null when the run recorded none. |
chainId | integer | null | EIP-155 id of chain. |
createdAt | string | ISO 8601 timestamp. |
status | "complete" | "locked" | locked: the balance ran out during the analysis and part of the price is still owed. See locked runs. |
priceUsd | number | What the run cost you. |
free | boolean | One of a new account's free analyses. priceUsd is 0. |
txType | string | Present when the run classified the transaction. |
keyId | string | The key that started the run. Absent for runs started in the web app. |
summary | string | The first ~200 characters of the summary. |
links.self | string | null | Path of the run, for example /runs/4815162342. |
nextOffset | integer | null | The offset for the next page. null on the last page. |
GET /runs/:runId
One of your runs with the full report it delivered.
Parameters
| Param | Type | Required | Description |
|---|---|---|---|
runId | integer (path) | yes | A run id from GET /runs. |
200 OK
The same fields as a list item (with the full summary, and without links), plus the report:
| Field | Type | Notes |
|---|---|---|
result | ExplanationResult | null | The result the run delivered. Schema in POST /explain → Response. |
html | string | The HTML report, for a run requested with report: true. Such a run stored only the HTML, so result is null. |
resultOmitted | string | Why no report is available, when neither result nor html is present. |
Locked runs
A run whose balance ran out mid-analysis, with part of its price still owed, answers 402:
{
"error": "This report is locked: ...",
"code": "charge_incomplete",
"runId": 4815162342,
"owedUsd": 0.48,
"links": { "unlock": "/explain/run/..." }
}This route does not collect the remainder. A GET on links.unlock with the same key pays it from your balance and returns the report.
A run whose charge is still being confirmed from the ledger record answers the same 402, and owedUsd is what the unlock will actually collect: only the remainder, never the full price again. Where there is nothing left to collect, or the remainder cannot be read back from the ledger record, the 402 carries no owedUsd at all. In that last case the unlock answers 409 run_settling and the run stays locked.
Errors
| Status | code | Meaning |
|---|---|---|
401 | unauthorized | No credential. The response carries WWW-Authenticate: Bearer. |
401 | invalid_api_key | The key is revoked, mistyped, or not enabled. |
402 | charge_incomplete | The run is locked. See locked runs. |
404 | not_found | No such run, or it belongs to another account. The answer is the same either way. |
409 | run_settling | The run's final charge is still being taken. Retry in a moment. |
Example
# Your 5 most recent runs
curl -s "https://mpp.oculr.xyz/runs?limit=5" -H "Authorization: Bearer $OCULR_API_KEY"
# The full report of one of them
curl -s "https://mpp.oculr.xyz/runs/4815162342" -H "Authorization: Bearer $OCULR_API_KEY"The machine-readable contract for both routes is in /openapi.json (listRuns, getRun).