# Run observation and request recovery

> Base path: `/api/rpa/browser/v1`. This page explains the semantics of [node execution records](/browser-rpa/api/list-run-nodes) (`GET /runs/{runId}/nodes`) and how to use a [request receipt](/browser-rpa/api/get-request-receipt) (`GET /requests/{key}`) to recover a write request after a disconnect.


## What node execution records return

`GET /runs/{runId}/nodes` returns the **current record** of each logical node invocation. It is not an event log. `items[].id` identifies one invocation. Retries inside the same invocation update the attempts/status/data/error of that id. The next loop iteration or a new child workflow invocation gets a new id. data/error reflect the current or last attempt; the full attempt history is not provided. Clients update their cache by id and must not merge records by nodeId alone.

A record is published when an invocation starts. Nodes that haven't started, or that a condition skipped, have no execution record. A missing record doesn't mean failure; a missed run can have no node records at all. Records are appended in a stable order of first publication, which the server persists internally. Status updates don't change this order. The order is not by startedAt or nodeId, and no sort or incremental parameters are available. While records are retained, no individual record is removed. Cleanup of a whole run still follows the resource retention and permission rules.

### Filtering and pagination

| Parameter | Purpose |
|  --- | --- |
| nodeId | Get all invocation records of one template node. A loop can produce several. |
| workflowRevisionId | Restrict results to the exact revision of the root workflow or a child workflow. Use it to tell apart nodes that have the same ID. |
| invocationPath | Copy items[].invocationPath as is. Exact match only. It is an opaque string; don't guess its syntax or build it yourself. |
| executionId | Exactly matches items[].id, to query one known invocation. The response still calls it id; there is no separate executionId field. |
| status | A single node status: running/success/failed/cancelled. This is not the run status. |
| page / pageSize | Defaults are 1/20, and pageSize is 1–100. Keep the page size fixed within each scan round. |


All filters are combined with AND. Strings match the raw value exactly and case-sensitively, with no trimming or Unicode normalization. Empty strings, repeated query keys, multiple statuses joined with commas, unknown query parameters, and invalid enum values return 400. To get several nodes, query each one separately, or read the results without a nodeId filter and filter them locally. A valid filter with no matches, or a page number beyond the range, returns 200 with items=[] and total set to the current number of matches. A run that you have no access to, or that doesn't exist, is handled as 403/404. total is the number of records. It is not the number of template nodes or an event sequence number.

Examples (request paths only; they don't mean that any call was made):

```http
GET /api/rpa/browser/v1/runs/run_example/nodes?page=1&pageSize=30
GET /api/rpa/browser/v1/runs/run_example/nodes?nodeId=read_url&page=1&pageSize=30
GET /api/rpa/browser/v1/runs/run_example/nodes?status=failed&page=1&pageSize=30
GET /api/rpa/browser/v1/runs/run_example/nodes?executionId=node_execution_example
```

### Polling correctly

In each round, reread the selected set from page=1 and overwrite the cache by id. If the first read of 30 records has 20 success and 10 running, the second read still covers those 30 records, and they may now be 25 success, 3 failed, and 2 running. total can still be 30; don't append them locally to make 60 records. Don't continue from "the last nodeId", "the previous total", or "the last page" as a substitute for refreshing statuses. All of these approaches miss updates to older records.

While a run is in progress, pagination doesn't guarantee a consistent snapshot across pages. If a record disappears from status=running, that only proves this read didn't return it; a change in the filtered set may also have caused pagination to skip it. Reread it by executionId, or wait for the final check. Don't infer success, failure, or stopped. An empty list doesn't prove that the run has ended either.

We recommend that you determine the terminal state with [run details](/browser-rpa/api/get-run), and then read all pages of node execution records without filters as the final check. If you only care about one node, at least remove the status filter, and state that the report covers only that subset. The final node projection must be persisted before the run's terminal state is published. No record can remain running after the terminal state. An invocation whose end can't be confirmed is marked failed (error.code is OUTCOME_UNKNOWN or RPA_INTERRUPTED), and endedAt/durationMs can be null. Evidence of success, cancellation, or stopping is never fabricated. The terminal projection stays stable during the retention period. Later external status checks don't silently rewrite this result.

run.isolation describes isolation and the boundary for reusing the environment. It doesn't prove whether an action happened on the website, or how many times. An unknown outcome stays unknown and must not be run again automatically.

Every page request in every round counts toward the shared request budget. We recommend polling at least 3 seconds apart for active runs and at least 5 seconds apart for queued runs. Keep all observation and recovery requests combined at no more than 40 per minute. When there are many pages, lengthen the cycle of a full round. If the budget runs short, you can pause or abandon the current scan, but you must not report a partially read set as complete. The terminal-state check must read every page. If limits prevent that, say so explicitly.

### Data size

Local requests also need bounded responses. By default, capabilities.limits.nodeDataBytes=65536 and nodePageBytes=8388608. The capabilities response gives the actual values.

data is not redacted. It returns the actual values as is (only element and frame handles appear as `{kind,available:false}`). The byte size of data is measured as compact UTF-8 JSON (non-ASCII characters are output as is, without \u escapes). If data exceeds the per-record limit, the whole data is returned as null with dataTruncated=true. JSON is never cut off partway, and the node status/error is not affected. If no data was produced, data is null and dataTruncated=false. AI agents must not treat an omitted result as an empty result or as a run failure. There is currently no download endpoint that bypasses this limit.

If the complete compact response for a single page (including data, error, artifacts, and meta) exceeds the limit, the endpoint returns 413 RPA_LIMIT_EXCEEDED with details set to `{limit:"nodePageBytes",maxBytes:<actualLimit>}`. It doesn't silently return fewer items. The caller reduces pageSize and rescans from page=1. If pageSize=1 still exceeds the limit, report the limit and don't retry without bound. Don't mistake the request body limit for the response limit.

## Request IDs and run IDs

[Get a request receipt](/browser-rpa/api/get-request-receipt) uses the path `GET /requests/{key}`, and its operationId is `getRequestReceipt`.

| ID | Generated by | Purpose |
|  --- | --- | --- |
| Idempotency-Key / path key | The caller's tool or SDK generates a UUID before sending and stores it persistently. | Identifies one business write intent and lets you retrieve the outcome after a disconnect. Regular users don't need to enter it by hand. |
| meta.requestId | The server generates it for each HTTP request it handles. | Troubleshooting and tracing. A retry with the same key still gets a different requestId, so you can't use it to retrieve a response you haven't received. |
| runId | The server generates it when it registers a run. | Query run details and node execution results. |


If you receive the 202 response to POST /runs normally, use data.id directly. You don't need to query the request receipt. A timeout or disconnect only means "no result was received". It must not be called "creation failed". Query with the original key. For accepted, wait. committed means the business write was committed and is waiting to be published; don't register the run again. For completed with operation=startRun, resourceId=result.id=runId, and result is the RunSummary **as registered at that time**, not the current execution result. After you have the runId, query [run details](/browser-rpa/api/get-run) and [node execution records](/browser-rpa/api/list-run-nodes). failed is a failure for which it is confirmed that the request made no business commit. unknown stays uncertain; don't generate a new key to run again.

An ordinary 404 doesn't prove that nothing was created. Only RPA_REQUEST_NOT_COMMITTED with details.safeToRetrySameKey=true allows recovery with the original key and the original request. A new body or a new If-Match is a new intent, so you must first resolve the uncertain outcome of the original intent. Replay expiry after 24 hours and the tombstone rules follow the [recovery matrix](/browser-rpa/api/recovery). Only resource IDs that the current authorization allows can be returned. An original delete request is recovered under the tombstone permissions; the request is not wrongly reported as nonexistent just because the resource was deleted.

Request receipts apply to all write requests. For createTemplate, resourceId is the templateId; for startRun, it is the runId. Don't treat every resourceId as a runId.

Receipts and resources are visible only within the data scope of the original account/team/member. Switching the account, team, or member moves you to a different storage, so not finding an old receipt doesn't prove that the original request didn't run. Changing the authentication token doesn't change the current data scope. RPA has no separate per-resource authorization or revocation.