> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Leer resultados de análisis
> El orden y las reglas para interpretar una respuesta de GET /analyses/:analysisId — el sobre de extractedData, por qué los campos están vacíos, los veredictos, la congelación del playbook y el registro de auditoría.
[`GET /analyses/:analysisId`](/es/omni/api-reference/get-analysis) devuelve más de 30 campos. Esta página no trata de definiciones de campos, sino **del orden en que leerlos y de cómo interpretarlos**. Para la lista de campos y sus tipos, consulte la referencia de la API; para la terminología, [conceptos clave](/es/omni/getting-started/core-concepts).
## El orden de lectura
No siga adelante si no es `completed`. En `failed`, registre `error.code` y `error.message` y revise el estado de los ítems.
`extractedData` sigue la estructura del output schema solo cuando `systemMetadata.outputFormatting.status` es `formatted` o `validation_failed`. Con `skipped` o `fallback_raw` no hay sobre (vea más abajo).
`verified` → aprobar automáticamente, `pending_review` → cola de revisión, `rejected` → rechazar. Los veredictos de detalle vienen después.
Los valores están en el `value` del sobre, el motivo en `reasoning`, y la causa de un campo vacío es el `reasonCode` de `details[]`.
Qué paso decidió qué y con qué fundamentos, y si las llamadas a motores externos tuvieron éxito, está todo en el registro de auditoría.
## El sobre de `extractedData`
Cada **campo final** del output schema lleva un objeto con tres claves en lugar de un valor suelto. Los objetos intermedios y las estructuras de array siguen su esquema exactamente.
| Clave | Tipo | Significado |
| ------------ | ------------------------------ | ------------------------------------------------------------------------------------------- |
| `value` | El tipo que declaró su esquema | El valor extraído. `null` cuando no se pudo obtener |
| `reasoning` | `string \| null` | Por qué el valor salió así. `null` cuando no se pudo suministrar un motivo |
| `sourceStep` | `number \| null` | El `agentAuditLog.steps[].step` del paso que lo rellenó. `null` cuando no se puede rastrear |
```json theme={null}
{
"extractedData": {
"company": {
"legal_name": {
"value": "ACME TRADING LLC",
"reasoning": "The legal name on the certificate of good standing matches the account holder on the bank verification letter.",
"sourceStep": 1
},
"state_file_number": {
"value": null,
"reasoning": "The state file number was not included in the extraction result.",
"sourceStep": 1
}
},
"ubo_register": [
{ "name": { "value": "John Carter", "reasoning": "Row 1 of the beneficial ownership certification", "sourceStep": 6 },
"share_pct": { "value": 60, "reasoning": "Row 1 of the beneficial ownership certification", "sourceStep": 6 } }
]
}
}
```
Las reglas:
* Un campo que no obtuvo valor **mantiene su sitio**, con `value: null`. La lista de campos de `extractedData` siempre coincide con el output schema.
* Cuando el propio objeto padre no se produjo, las rutas por debajo no se crean. En ese caso, `details[]` lleva una entrada para el padre con `reasonCode: "PARENT_MISSING"`.
* `reasoning` se guarda en el momento en que el análisis se completa. Volver a leer el análisis nunca lo cambia.
* `sourceStep` es un número de orden de ejecución, así que puede cambiar a partir del siguiente análisis si edita el workflow. Para señalar un paso de forma fiable, use `agentAuditLog.steps[].work_id`.
* `0` y `false` son valores válidos. Vacío significa `null` / `""` / `[]` / `{}`.
### Cuando no hay sobre
| Condición | Cómo distinguirlo | Forma de `extractedData` |
| ------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| El workflow no tiene output schema | `outputSchema === null` y `outputFormatting.status === "skipped"` | El resultado bruto indexado por nombre de acción (la misma estructura que `rawActionResults`) |
| Falló el ensamblado del output schema | `outputFormatting.status === "fallback_raw"`, con el motivo en `outputFormatting.error` | Igual que arriba |
`fallback_raw` es la causa más frecuente de "todos los campos del output schema parecen vacíos". Bifurque según `status` antes de buscar valores por clave del esquema. `validation_failed` significa que el ensamblado funcionó pero algunas entradas no validan contra el esquema: el sobre es normal, y las discrepancias están en `ajvErrors[]`.
Los análisis completados antes del 2026-08-14 no tienen `outputFormatting`. Para esos, decida si hay sobre comprobando si `outputSchema` es `null`.
## Por qué un campo está vacío
Un campo que no recibió valor permanece en el sobre con `value: null`, y se añade a `details[]` una entrada con `category: "JSON_OUTPUT"` que baja `outputCompleteness` en el Analysis Score.
```json theme={null}
{
"category": "JSON_OUTPUT",
"type": "OUTPUT_MISSING",
"target": "company.state_file_number",
"reasonCode": "NOT_IN_FINAL_OUTPUT",
"message": "The legal name and the registered agent were confirmed on the certificate, but no state file number entry was found.",
"stepId": 1
}
```
| `reasonCode` | Significado |
| --------------------- | ------------------------------------------------------------------------------ |
| `PARENT_MISSING` | El padre está ausente o vacío, así que el hijo tampoco se produjo |
| `EMPTY_VALUE` | La clave existe pero el valor es `null` / `""` / `[]` / `{}` |
| `NOT_IN_FINAL_OUTPUT` | La clave no está en la salida final ensamblada |
| `TOOL_ERROR` | La llamada al motor externo del paso responsable quedó registrada como fallida |
* `reasonCode` es un **enumerado ampliable**. Maneje sin error un valor fuera de la tabla. Es un eje distinto de `type` (un conjunto fijo de seis, como `OUTPUT_MISSING` y `OUTPUT_EMPTY`).
* `reasonCode`, `message` y `stepId` aparecen solo en entradas `JSON_OUTPUT`, nunca en entradas `STEP` ni `TOOL`.
* `message` son los fundamentos que registró el **paso** responsable, mientras que el `reasoning` del sobre da el motivo a nivel de **campo**. Las dos frases pueden diferir, así que lea primero `reasoning` para el contexto del campo.
* `target` es una ruta de instancia real. Los arrays se despliegan por índice, uno por elemento (`ubo_register[0].name`). Un array vacío, o una clave de array ausente, cuenta como una sola entrada `ubo_register`.
* Omni no vuelve a examinar el documento original. Nunca afirma que "el valor no estaba en el documento"; lo máximo que dice es que "no se incluyó en el resultado de la extracción" (`NOT_IN_FINAL_OUTPUT`).
### Cuando no se puede suministrar un motivo
| Situación | `reasoning` | `reasonCode` en `details[]` |
| ----------------------------------------------------------------- | -------------------------- | -------------------------------------- |
| Sin output schema, o `fallback_raw` | No hay sobre en absoluto | Ninguno |
| Análisis completado antes de que existiera esta función (2026-08) | `null` en todos los campos | Ninguno |
| Solo falló la correspondencia con el paso | Normal | Normal, pero `stepId` puede ser `null` |
`reasoning: null` no significa "no hubo fundamentos", sino "no se pudo suministrar un motivo". Los motivos no se generan de forma retroactiva para análisis anteriores.
### No use extractionStatus
`extractionStatus` es un campo **obsoleto** que se mantiene por compatibilidad. Trabaja al nivel de las claves de primer nivel del esquema (`extracted` / `missing`), así que no distingue campos anidados ni elementos de array. Las integraciones nuevas deben usar el `value` del sobre junto con `details[]`. Su regla de vacío coincide con la del sobre (`0` y `false` cuentan como `extracted`). En un análisis sin output schema, devuelve un mapa indexado por las claves de primer nivel de `extractedData`.
## Leer los veredictos
La respuesta contiene tres niveles de veredictos con nombres parecidos, cada uno con un conjunto de valores distinto.
| Nivel | Campo | Valores |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Todo el análisis | `verificationStatus` | `verified` / `pending_review` / `rejected` |
| Una acción del playbook | `agentAuditLog.steps[].status`, `agentAuditLog.summary.overall_decision`, `rawActionResults.{acción}.verificationStatus`, `systemMetadata.workflowHistory[].verificationStatus` | `passed` / `needs_review` / `failed` |
| Un campo de estado dentro del output schema | `extractedData.{...}` | Lo que haya definido su workflow. No es un veredicto del sistema |
El veredicto de nivel superior agrega los resultados de las acciones. Un `failed` lo convierte en `rejected`, todos `passed` en `verified`, y cualquier otra combinación en `pending_review`. `summary.overall_decision` es el mismo agregado, de modo que `passed` → `verified`, `needs_review` → `pending_review` y `failed` → `rejected`. `findings[].result` es ese mismo resultado traducido para la interfaz (`needs_review` pasa a `warning`).
### `confidence` frente a `confidenceScore`
| | `confidence` | `confidenceScore` |
| --------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Tipo | `object` (`score` 0–100, `level`, `components`) | `number` 0.0–1.0, o `null` |
| Significado | **Analysis Score** — cuán completa es la salida | La confianza del agente en el veredicto |
| Cómo se calcula | 40% ejecución de pasos + 20% calidad de pasos + 40% completitud de la salida | En `verified`, la confianza media de las acciones superadas; en el resto, un valor fijo |
Un `confidenceScore` alto puede convivir con un `confidence.score` bajo. El caso típico es que todos los pasos pasen mientras el output schema vuelve vacío. Incluya `confidence.score` y `details[]` junto a `verificationStatus` en sus condiciones de aprobación automática. Los pesos y los tramos de nivel están en [conceptos clave](/es/omni/getting-started/core-concepts#analysis-score).
## Qué playbook produjo este veredicto
Un análisis congela el playbook tal como estaba al ejecutarse y lo devuelve como `playbookSnapshot`. Editar el workflow después deja intactos los fundamentos de los análisis anteriores.
| `snapshotStatus` | Significado | `playbookSnapshot` · `playbookVersion` · `capturedAt` |
| ---------------- | -------------------------------------------------- | -------------------------------------------------------------------------- |
| `frozen` | Existe una instantánea del momento de la ejecución | Según la instantánea |
| `legacy` | Analizado antes de que existieran las instantáneas | Se sustituye por el cuerpo del playbook actual; versión y fecha son `null` |
| `missing` | No queda ninguna instantánea | Igual que arriba |
Si conserva los fundamentos con fines de auditoría, guarde el `playbookSnapshot` de los análisis marcados como `frozen`. `outputSchema` se congela del mismo modo.
## Leer el registro de auditoría
`agentAuditLog` es el registro de ejecución paso a paso. A diferencia de los campos de nivel superior, usa **snake\_case** (`work_id`, `executed_at`, `duration_ms`).
* Identificar un paso: `step` es el orden de ejecución y `work_id` es el ID fijo de la acción del playbook. Se corresponde con `workflowActions[].workId` de [`GET /workflows/:workflowId`](/es/omni/api-reference/get-workflow).
* Veredictos de paso: `status` (`passed` / `needs_review` / `failed`) y `reasoning` son lo que la pestaña Summary muestra como línea de razonamiento en el panel. `rule` es la instrucción que llevó a cabo ese paso.
* Llamadas a motores externos: juzgue el fallo por `success` y `error_code` en `mcpcalls[]`. No hay código de estado HTTP. `fallback_to_rag: true` significa que, tras fallar el motor, se recurrió a la búsqueda documental.
* Para ver esas mismas llamadas organizadas por acción, use `rawActionResults.{acción}.mcpResults[]`. Ese lado usa **camelCase** (`durationMs`, `errorCode`, `fallbackToRag`).
* Un paso que nunca se ejecutó tampoco aparece en `systemMetadata.workflowHistory[]`. Las definiciones completas de los pasos están en `workflowActions` de la respuesta del workflow, y un paso no ejecutado queda registrado en `details[]` como `STEP_NOT_EXECUTED`.
## Un patrón para el procesamiento posterior
```python theme={null}
a = get_analysis(analysis_id)
if a["status"] != "completed":
return retry_later()
fmt = a.get("systemMetadata", {}).get("outputFormatting")
raw_mode = fmt is None and a["outputSchema"] is None or (fmt and fmt["status"] in ("skipped", "fallback_raw"))
if a["verificationStatus"] == "verified" and a["confidence"]["score"] >= 80 and not raw_mode:
approve(a["extractedData"])
elif a["verificationStatus"] == "rejected":
reject(reason=[s for s in a["agentAuditLog"]["steps"] if s["status"] == "failed"])
else:
route_to_reviewer(a, missing=[d for d in a["details"] if d["category"] == "JSON_OUTPUT"])
```
* Mostrar a un revisor el `target`, el `reasonCode` y el `message` de `details[]` junto al `reasoning` del sobre hace que encuentre la causa mucho antes.
* Volver a analizar el mismo perfil tras mejorar los ítems emite un `analysisId` nuevo. El resultado anterior se conserva, y puede compararlos con el selector de ejecución del panel.
* Cuando necesite un informe que pueda leer una persona, obtenga el PDF con [`GET /analyses/:analysisId/report`](/es/omni/api-reference/get-report).