Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

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 /explain and POST /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

ParamTypeRequiredDescription
limitinteger (query)noRuns per page, 1 to 50. Default 20. Values outside the range are clamped.
offsetinteger (query)noHow 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
}
FieldTypeNotes
idinteger | nullThe 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.
txHashstringThe transaction that was analysed.
chainstring | nullChain slug the transaction was found on. null when the run recorded none.
chainIdinteger | nullEIP-155 id of chain.
createdAtstringISO 8601 timestamp.
status"complete" | "locked"locked: the balance ran out during the analysis and part of the price is still owed. See locked runs.
priceUsdnumberWhat the run cost you.
freebooleanOne of a new account's free analyses. priceUsd is 0.
txTypestringPresent when the run classified the transaction.
keyIdstringThe key that started the run. Absent for runs started in the web app.
summarystringThe first ~200 characters of the summary.
links.selfstring | nullPath of the run, for example /runs/4815162342.
nextOffsetinteger | nullThe offset for the next page. null on the last page.

GET /runs/:runId

One of your runs with the full report it delivered.

Parameters

ParamTypeRequiredDescription
runIdinteger (path)yesA run id from GET /runs.

200 OK

The same fields as a list item (with the full summary, and without links), plus the report:

FieldTypeNotes
resultExplanationResult | nullThe result the run delivered. Schema in POST /explain → Response.
htmlstringThe HTML report, for a run requested with report: true. Such a run stored only the HTML, so result is null.
resultOmittedstringWhy 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

StatuscodeMeaning
401unauthorizedNo credential. The response carries WWW-Authenticate: Bearer.
401invalid_api_keyThe key is revoked, mistyped, or not enabled.
402charge_incompleteThe run is locked. See locked runs.
404not_foundNo such run, or it belongs to another account. The answer is the same either way.
409run_settlingThe 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).