# Observación de ejecuciones y recuperación de solicitudes

> Ruta base: `/api/rpa/browser/v1`. Esta página explica la semántica de los [registros de ejecución de nodos](/es/browser-rpa/api/list-run-nodes) (`GET /runs/{runId}/nodes`) y cómo usar un [recibo de solicitud](/es/browser-rpa/api/get-request-receipt) (`GET /requests/{key}`) para recuperar una solicitud de escritura después de una desconexión.


## Qué devuelven los registros de ejecución de nodos

`GET /runs/{runId}/nodes` devuelve el **registro actual** de cada invocación lógica de un nodo. No es un historial de eventos. `items[].id` identifica una invocación. Los reintentos dentro de la misma invocación actualizan attempts/status/data/error de ese id. La siguiente iteración del bucle o una nueva invocación de un flujo secundario recibe un id nuevo. data/error reflejan el intento actual o el último; no se proporciona el historial completo de intentos. Los clientes actualizan su caché por id y no deben combinar los registros solo por nodeId.

Un registro se publica cuando se inicia una invocación. Los nodos que no se han iniciado, o que una condición omitió, no tienen registro de ejecución. La ausencia de un registro no significa un fallo; una ejecución con estado missed puede no tener ningún registro de nodos. Los registros se agregan en un orden estable según su primera publicación, que el servidor almacena internamente. Las actualizaciones de estado no cambian este orden. El orden no se basa en startedAt ni en nodeId, y no hay parámetros de ordenación ni incrementales. Mientras se conservan los registros, no se elimina ningún registro individual. La limpieza de una ejecución completa sigue sujeta a las reglas de retención de recursos y de permisos.

### Filtrado y paginación

| Parámetro | Finalidad |
|  --- | --- |
| nodeId | Obtiene todos los registros de invocación de un nodo de la plantilla. Un bucle puede producir varios. |
| workflowRevisionId | Limita los resultados a la revisión exacta del flujo de trabajo raíz o de un flujo secundario. Úsalo para distinguir nodos que tienen el mismo ID. |
| invocationPath | Copia items[].invocationPath tal cual. Solo coincidencia exacta. Es una cadena opaca; no adivines su sintaxis ni la construyas tú mismo. |
| executionId | Coincide exactamente con items[].id, para consultar una invocación conocida. La respuesta lo sigue llamando id; no hay un campo executionId independiente. |
| status | Un único estado de nodo: running/success/failed/cancelled. No es el estado de la ejecución. |
| page / pageSize | Los valores predeterminados son 1/20, y el rango de pageSize es 1–100. Mantén fijo el tamaño de página en cada pasada del recorrido. |


Todos los filtros se combinan con AND. Las cadenas se comparan con el valor sin procesar de forma exacta y distinguiendo entre mayúsculas y minúsculas, sin quitar espacios ni aplicar normalización Unicode. Las cadenas vacías, las claves de consulta repetidas, varios estados unidos por comas, los parámetros de consulta desconocidos y los valores de enumeración no válidos devuelven 400. Para obtener varios nodos, consulta cada uno por separado, o lee los resultados sin el filtro nodeId y fíltralos localmente. Un filtro válido sin coincidencias, o un número de página fuera del rango, devuelve 200 con items=[] y total con el número actual de coincidencias. Una ejecución a la que no tienes acceso, o que no existe, se trata como 403/404. total es el número de registros. No es el número de nodos de la plantilla ni un número de secuencia de eventos.

Ejemplos (solo rutas de solicitud; no significan que se haya hecho ninguna llamada):

```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
```

### Cómo consultar correctamente

En cada pasada, vuelve a leer el conjunto seleccionado desde page=1 y sobrescribe la caché por id. Si la primera lectura de 30 registros tiene 20 en success y 10 en running, la segunda lectura sigue abarcando esos 30 registros, que ahora pueden ser 25 en success, 3 en failed y 2 en running. total puede seguir siendo 30; no los agregues localmente hasta formar 60 registros. No continúes desde "el último nodeId", "el total anterior" o "la última página" en lugar de actualizar los estados. Todos estos enfoques pierden las actualizaciones de los registros más antiguos.

Mientras una ejecución está en curso, la paginación no garantiza una instantánea coherente entre páginas. Si un registro desaparece de status=running, eso solo demuestra que esta lectura no lo devolvió; un cambio en el conjunto filtrado también puede haber hecho que la paginación lo omitiera. Vuelve a leerlo por executionId o espera a la comprobación final. No deduzcas un éxito, un fallo ni un estado stopped. Una lista vacía tampoco demuestra que la ejecución haya terminado.

Te recomendamos determinar el estado terminal con los [detalles de la ejecución](/es/browser-rpa/api/get-run) y, después, leer todas las páginas de los registros de ejecución de nodos sin filtros como comprobación final. Si solo te interesa un nodo, quita al menos el filtro de estado e indica que el informe solo abarca ese subconjunto. La proyección final de los nodos debe guardarse de forma persistente antes de que se publique el estado terminal de la ejecución. Ningún registro puede seguir en running después del estado terminal. Una invocación cuyo final no se puede confirmar se marca como failed (error.code es OUTCOME_UNKNOWN o RPA_INTERRUPTED), y endedAt/durationMs pueden ser null. Nunca se inventan evidencias de éxito, cancelación o detención. La proyección terminal se mantiene estable durante el período de retención. Las comprobaciones de estado externas posteriores no reescriben este resultado de forma silenciosa.

run.isolation describe el aislamiento y el límite para reutilizar el entorno. No demuestra si una acción ocurrió en el sitio web ni cuántas veces. Un resultado desconocido sigue siendo desconocido y no debe volver a ejecutarse automáticamente.

Cada solicitud de página de cada pasada cuenta para el presupuesto de solicitudes compartido. Te recomendamos consultar las ejecuciones activas con al menos 3 segundos de intervalo y las ejecuciones en cola con al menos 5 segundos de intervalo. Mantén todas las solicitudes de observación y de recuperación, en conjunto, en un máximo de 40 por minuto. Cuando haya muchas páginas, alarga el ciclo de una pasada completa. Si el presupuesto no alcanza, puedes pausar o abandonar el recorrido actual, pero no debes informar un conjunto leído parcialmente como completo. La comprobación del estado terminal debe leer todas las páginas. Si los límites lo impiden, indícalo explícitamente.

### Tamaño de los datos

Las solicitudes locales también necesitan respuestas acotadas. De forma predeterminada, capabilities.limits.nodeDataBytes=65536 y nodePageBytes=8388608. La respuesta de capacidades indica los valores reales.

data no se oculta. Devuelve los valores reales tal como son (solo los manejadores de elementos y de marcos aparecen como `{kind,available:false}`). El tamaño en bytes de data se mide como JSON UTF-8 compacto (los caracteres no ASCII se emiten tal cual, sin escapes \u). Si data supera el límite por registro, todo data se devuelve como null con dataTruncated=true. El JSON nunca se corta a medias, y el status/error del nodo no se ve afectado. Si no se produjeron datos, data es null y dataTruncated=false. Los agentes de IA no deben tratar un resultado omitido como un resultado vacío ni como un fallo de la ejecución. Actualmente no hay ningún endpoint de descarga que evite este límite.

Si la respuesta compacta completa de una sola página (incluidos data, error, artifacts y meta) supera el límite, el endpoint devuelve 413 RPA_LIMIT_EXCEEDED con details establecido en `{limit:"nodePageBytes",maxBytes:<actualLimit>}`. No devuelve menos elementos de forma silenciosa. El llamador reduce pageSize y vuelve a recorrer desde page=1. Si con pageSize=1 se sigue superando el límite, informa el límite y no reintentes indefinidamente. No confundas el límite del cuerpo de la solicitud con el límite de la respuesta.

## ID de solicitud e ID de ejecución

[Obtener un recibo de solicitud](/es/browser-rpa/api/get-request-receipt) usa la ruta `GET /requests/{key}`, y su operationId es `getRequestReceipt`.

| ID | Generado por | Finalidad |
|  --- | --- | --- |
| Idempotency-Key / clave de la ruta | La herramienta o el SDK del llamador genera un UUID antes del envío y lo guarda de forma persistente. | Identifica una intención de escritura de negocio y permite recuperar el resultado después de una desconexión. Los usuarios normales no necesitan introducirlo a mano. |
| meta.requestId | El servidor lo genera para cada solicitud HTTP que gestiona. | Solución de problemas y seguimiento. Un reintento con la misma clave recibe igualmente un requestId distinto, por lo que no puedes usarlo para recuperar una respuesta que no recibiste. |
| runId | El servidor lo genera cuando registra una ejecución. | Consultar los detalles de la ejecución y los resultados de ejecución de los nodos. |


Si recibes con normalidad la respuesta 202 de POST /runs, usa data.id directamente. No necesitas consultar el recibo de solicitud. Un tiempo de espera agotado o una desconexión solo significa "no se recibió ningún resultado". No debe describirse como "la creación falló". Consulta con la clave original. Ante accepted, espera. committed significa que la escritura de negocio se confirmó y está pendiente de publicarse; no vuelvas a registrar la ejecución. Ante completed con operation=startRun, resourceId=result.id=runId, y result es el RunSummary **tal como se registró en ese momento**, no el resultado de ejecución actual. Cuando tengas el runId, consulta los [detalles de la ejecución](/es/browser-rpa/api/get-run) y los [registros de ejecución de nodos](/es/browser-rpa/api/list-run-nodes). failed es un fallo para el que se comprobó que la solicitud no realizó ninguna confirmación de negocio. unknown sigue siendo incierto; no generes una clave nueva para volver a ejecutar.

Un 404 ordinario no demuestra que no se haya creado nada. Solo RPA_REQUEST_NOT_COMMITTED con details.safeToRetrySameKey=true permite recuperar con la clave original y la solicitud original. Un cuerpo nuevo o un If-Match nuevo es una intención nueva, así que primero debes resolver el resultado incierto de la intención original. La caducidad de la reproducción a las 24 horas y las reglas del marcador de eliminación se rigen por la [matriz de recuperación](/es/browser-rpa/api/recovery). Solo se pueden devolver los ID de recursos que permite la autorización actual. Una solicitud de eliminación original se recupera según los permisos del marcador de eliminación; la solicitud no se informa erróneamente como inexistente solo porque el recurso se eliminó.

Los recibos de solicitud se aplican a todas las solicitudes de escritura. En createTemplate, resourceId es el templateId; en startRun, es el runId. No trates todos los resourceId como un runId.

Los recibos y los recursos solo son visibles dentro del ámbito de datos de la cuenta/equipo/miembro original. Al cambiar de cuenta, de equipo o de miembro pasas a un almacenamiento distinto, por lo que no encontrar un recibo anterior no demuestra que la solicitud original no se haya ejecutado. Cambiar el token de autenticación no cambia el ámbito de datos actual. RPA no tiene una autorización ni una revocación independientes por recurso.