GET /analyses/:analysisId

Endpoint

GET /v1/analyses/{analysisId}

Solicitud

curl -X GET "http://client-omni-api.argosidentity.com/v1/analyses/{analysisId}?waitForReport=true&timeoutSeconds=120" \
  -H "x-api-key: your-api-key-here"

Query Parameters

Parameter	Type	Required	Default	Descripción
`waitForReport`	`boolean`		`false`	Espera a que se genere el report (long polling)
`timeoutSeconds`	`number`		`120`	Tiempo máximo de espera en segundos (10-300)

Cuando waitForReport es true, la solicitud mantiene la conexión abierta hasta que se genere el report o se alcance el umbral de timeoutSeconds. Esto es útil para flujos síncronos donde necesita el report inmediatamente después de completar el análisis.

Estructura de la respuesta

La respuesta del análisis tiene un esqueleto fijo (campos de nivel superior, risk assessment, metadatos del sistema, findings, etc.) que siempre está presente independientemente de la configuración del workflow.

Las secciones extractedData y outputSchema están determinadas por la configuración del output schema de su workflow. Los campos dentro de ellas cambian según cómo haya definido su output schema. El ejemplo a continuación muestra un workflow de verificación KYB; sus resultados tendrán campos diferentes según su propio schema.

Campos de nivel superior

Estos campos están siempre presentes en cada respuesta de análisis.

string

requerido

ID único del análisis (prefijo analysis_)

profileId

string

requerido

ID del profile al que pertenece este análisis

folderId

string | null

requerido

ID del folder objetivo (null para análisis de profile completo)

engineId

string | null

requerido

ID del engine utilizado (null cuando se usa el engine predeterminado)

playbookId

string

requerido

ID del playbook utilizado para el análisis (prefijo PB-)

engine

object | null

requerido

Detalles del engine (null cuando se usa el engine predeterminado)

status

string

requerido

Estado del análisis: pending / processing / completed / failed

processingTimeMs

number

requerido

Tiempo de procesamiento en milisegundos

verificationStatus

string

requerido

Estado final de verificación: pending_review / approved / rejected

error

string | null

requerido

Mensaje de error (null si fue exitoso)

options

object | null

Opciones pasadas cuando se solicitó el análisis

clientMetadata

object | null

Metadata del cliente pasada cuando se solicitó el análisis

primaryReportId

string | null

ID del report principal generado para este análisis (prefijo rpt_)

requestedAt

string

requerido

Hora de solicitud del análisis (ISO 8601)

completedAt

string | null

requerido

Hora de finalización del análisis (ISO 8601, null si no se ha completado)

createdAt

string

requerido

Hora de creación del registro (ISO 8601)

`riskAssessment` — Evaluación de riesgo

Evaluación de riesgo final calculada por el agente de IA después de todos los pasos de verificación.

Field	Type	Descripción
`riskLevel`	`string`	Nivel de riesgo: `low` / `medium` / `high`
`riskScore`	`number`	Puntuación de riesgo (0-100, mayor = más riesgoso)
`riskFactors`	`string[]`	Lista de factores que contribuyen al nivel de riesgo

`systemMetadata` — Metadatos de ejecución

Información interna de ejecución del agente de IA durante el análisis.

Field	Type	Descripción
`totalIterations`	`number`	Total de iteraciones realizadas por el agente
`completedWorkIds`	`number[]`	IDs de los work items completados exitosamente
`workflowHistory`	`object[]`	Resumen de ejecución de cada work item

`systemMetadata.workflowHistory[]`

Field	Type	Descripción
`workId`	`number`	Número de secuencia del work (comienza en 1)
`actionName`	`string`	Nombre de la función de acción ejecutada
`query`	`string`	Consulta/instrucción utilizada por el agente
`reason`	`string`	Razonamiento del agente para el resultado
`success`	`boolean`	Si el work fue exitoso
`iteration`	`number`	Número de iteración al completarse
`timestamp`	`string`	Hora de finalización (ISO 8601)

`extractedData` — Datos estructurados extraídos

Esta sección es dinámica. Los campos dentro de extractedData están determinados por el output schema definido en su workflow. El ejemplo a continuación es de un workflow KYB con verificación de registro empresarial; sus campos serán diferentes.

La IA extrae datos de los documentos y los estructura según su output schema. Las siguientes subsecciones son patrones comunes:

`extractedData.review_result` — Resultado final de revisión

Field	Type	Descripción
`final_action`	`string`	Acción final: `approve` / `reject` / `manual_review`
`final_risk_level`	`string`	Nivel de riesgo final: `low` / `medium` / `high`
`final_action_reason`	`string`	Razonamiento de la acción final
`final_risk_level_reason`	`string`	Razonamiento del nivel de riesgo final

`extractedData.extracted_values` — Valores extraídos en bruto

Valores extraídos directamente de los documentos enviados. Los campos dependen de la definición de su output schema. Ejemplo (KYB con registro empresarial):

Field	Type	Descripción
`brc_business_name`	`string`	Nombre de la empresa del certificado de registro empresarial
`brc_business_registration_number`	`string`	Número de registro empresarial
`brc_corporate_registration_number`	`string`	Número de registro corporativo
`brc_representative_name`	`string`	Nombre del representante
`brc_address`	`string`	Dirección de la empresa
`brc_opening_date`	`string`	Fecha de apertura
`brc_issue_date`	`string`	Fecha de emisión

`extractedData.category_judgements` — Juicios de verificación

Resultados de verificación por categoría con estado pass/fail y razonamiento.

Field	Type	Descripción
`{field}_check_result`	`string`	Resultado de la verificación: `pass` / `fail` / `unverifiable` / `needs_review`
`{field}_check_reason`	`string`	Razonamiento del resultado de la verificación
`overall_consistency_result`	`string`	Consistencia general: `pass` / `needs_review` / `fail`
`overall_consistency_reason`	`string`	Razonamiento de la consistencia general

`extractedData.document_validations` — Validez documental

Field	Type	Descripción
`{document}_is_valid`	`boolean`	Si el documento es válido
`{document}_is_valid_reason`	`string`	Razonamiento de la verificación de validez

`outputSchema` — Output schema enriquecido

Contiene los mismos datos que extractedData, estructurados como el JSON Schema de su workflow con los valores reales completados. Use extractedData como campo canónico.

Campos comunes en `outputSchema.properties`

Field	Type	Descripción
`request_id`	`string`	Identificador de solicitud (igual que el profile ID)
`policy_flags`	`string[]`	Flags de violación/advertencia de policy
`review_result`	`object`	Resultado final de revisión
`extracted_values`	`object`	Valores en bruto extraídos de los documentos
`category_judgements`	`object`	Juicios de verificación por categoría
`document_validations`	`object`	Resultados de validez documental
`recommended_next_steps`	`string[]`	Acciones de seguimiento recomendadas por la IA

`extractionStatus` — Estado de extracción de campos

Mapa de estado que indica si cada campo de nivel superior del output schema fue extraído exitosamente.

Valor	Significado
`"extracted"`	El campo fue extraído/generado exitosamente
`"missing"`	La extracción del campo falló (sin documento o información)

`rawActionResults` — Resultados de acciones en bruto

Datos de resultado en bruto devueltos por cada acción de IA. Las claves son actionName.

Field	Type	Descripción
`answer`	`string`	Texto del resultado de la acción (respuesta RAG o salida LLM)
`workId`	`number`	Número de secuencia del work
`citationsCount`	`number`	Número de fragmentos de citas utilizados
`verificationStatus`	`string`	Resultado de verificación: `passed` / `needs_review` / `failed`

`agentAuditLog[]` — Registro de auditoría del agente

Registro detallado de ejecución de cada paso realizado por el agente de IA. Más granular que rawActionResults; incluye detalles de llamadas MCP tool.

Field	Type	Descripción
`workId`	`number`	Número de secuencia del work
`actionName`	`string`	Nombre de la acción
`category`	`string`	Categoría de la acción. Ejemplos incluyen `Document Classification`, `Data Extraction`, `Format Validation`, `Status Validation`, `Data Consistency`, `Document Processing` y `mcp` (herramientas externas). Los valores reales dependen de la policy del workflow.
`query`	`string`	Consulta o instrucción enviada por el agente
`reasoning`	`string`	Razonamiento del agente (puede estar vacío)
`success`	`boolean`	Si la ejecución fue exitosa
`iteration`	`number`	Número de iteración
`durationMs`	`number`	Duración de la ejecución en milisegundos
`executedAt`	`string`	Hora de ejecución (ISO 8601)
`verificationStatus`	`string	null`	Resultado de verificación por paso cuando aplica (p. ej., `passed` / `needs_review` / `failed`). Puede omitirse para pasos que no producen un pass/fail (como algunas acciones solo MCP).
`targetItemIds`	`string[]`	IDs de items referenciados por esta acción
`ragResponse`	`object	null`	Resultado de consulta RAG (si aplica)
`mcpToolCalls`	`object[]	null`	Detalles de llamadas MCP tool (si aplica)

`agentAuditLog[].ragResponse`

Presente solo para acciones que realizaron consultas RAG.

Field	Type	Descripción
`answer`	`string`	Texto de respuesta generado por RAG
`citations`	`object[]`	Fragmentos de citas utilizados en la respuesta
`chunksSearched`	`number`	Número de fragmentos buscados
`processingTimeMs`	`number`	Tiempo de procesamiento RAG en milisegundos

`agentAuditLog[].mcpToolCalls[]`

Presente solo para acciones que llamaron herramientas MCP externas (p. ej., screening AML).

Field	Type	Descripción
`toolName`	`string`	Nombre de la herramienta MCP (p. ej., `search_individual`)
`engineCode`	`string`	Identificador del engine para esta herramienta (p. ej., `aml-search`)
`engineName`	`string`	Nombre visible del engine (p. ej., `AML Search - Person`)
`params`	`object`	Parámetros de la llamada a la herramienta
`success`	`boolean`	Si la llamada fue exitosa
`startedAt`	`string`	Hora de inicio de la llamada (ISO 8601)
`executionTimeMs`	`number`	Duración de la llamada a la herramienta en milisegundos
`rawContent`	`object`	Datos de respuesta en bruto de la herramienta
`fallbackToRag`	`boolean`	Si se activó el fallback a RAG por fallo
`selectionReason`	`string`	Razón del agente para seleccionar esta herramienta

`findings[]` — Hallazgos de verificación

Resumen ordenado del resultado de cada acción. Diseñado para visualización en UI.

Field	Type	Descripción
`id`	`string`	ID del hallazgo (prefijo `af_`)
`category`	`string`	Categoría (igual que el nombre de la acción)
`result`	`string`	Resultado: `passed` / `warning` / `failed`
`details`	`string`	Detalles del resultado (puede estar truncado)
`sortOrder`	`number`	Orden de visualización

`recommendations[]` — Recomendaciones

Recomendaciones de acciones de seguimiento generadas por el sistema.

Field	Type	Descripción
`id`	`string`	ID de la recomendación (prefijo `ar_`)
`content`	`string`	Contenido de la recomendación
`priority`	`number`	Prioridad (menor = mayor prioridad)
`sortOrder`	`number`	Orden de visualización

`targetItems[]` — Items objetivo

Items referenciados en este análisis.

Field	Type	Descripción
`itemId`	`string`	ID del item (prefijo `item_`)
`name`	`string`	Nombre del item
`type`	`string`	Tipo de item: `file` / `text` / `json`
`sourceRef`	`string	null`	Información de referencia de origen

Enumeraciones de estado

Estado del análisis
Estado de verificación
Nivel de riesgo
Resultado del hallazgo
Resultado de verificación

Valor	Descripción
`pending`	En espera de análisis
`processing`	Análisis en progreso
`completed`	Análisis completado
`failed`	Análisis fallido

Valor	Descripción
`pending_review`	Requiere revisión manual
`approved`	Aprobado
`rejected`	Rechazado

Valor	Descripción
`low`	Riesgo bajo
`medium`	Riesgo medio
`high`	Riesgo alto

Valor	Descripción
`passed`	Aprobado
`warning`	Advertencia (requiere revisión)
`failed`	Fallido

Valor	Descripción
`pass`	Coincidencia confirmada
`fail`	Discrepancia
`unverifiable`	No se puede verificar (documento ausente)
`needs_review`	Requiere revisión adicional

Descripción General

Referencia API

Endpoint

Solicitud

Query Parameters

Estructura de la respuesta

Campos de nivel superior

`riskAssessment` — Evaluación de riesgo

`systemMetadata` — Metadatos de ejecución

`systemMetadata.workflowHistory[]`

`extractedData` — Datos estructurados extraídos

`extractedData.review_result` — Resultado final de revisión

`extractedData.extracted_values` — Valores extraídos en bruto

`extractedData.category_judgements` — Juicios de verificación

`extractedData.document_validations` — Validez documental

`outputSchema` — Output schema enriquecido

Campos comunes en `outputSchema.properties`

`extractionStatus` — Estado de extracción de campos

`rawActionResults` — Resultados de acciones en bruto

`agentAuditLog[]` — Registro de auditoría del agente

`agentAuditLog[].ragResponse`

`agentAuditLog[].mcpToolCalls[]`

`findings[]` — Hallazgos de verificación

`recommendations[]` — Recomendaciones

`targetItems[]` — Items objetivo

Enumeraciones de estado

Descripción General

Referencia API

​Endpoint

​Solicitud

​Query Parameters

​Estructura de la respuesta

​Campos de nivel superior

​riskAssessment — Evaluación de riesgo

​systemMetadata — Metadatos de ejecución

​systemMetadata.workflowHistory[]

​extractedData — Datos estructurados extraídos

​extractedData.review_result — Resultado final de revisión

​extractedData.extracted_values — Valores extraídos en bruto

​extractedData.category_judgements — Juicios de verificación

​extractedData.document_validations — Validez documental

​outputSchema — Output schema enriquecido

​Campos comunes en outputSchema.properties

​extractionStatus — Estado de extracción de campos

​rawActionResults — Resultados de acciones en bruto

​agentAuditLog[] — Registro de auditoría del agente

​agentAuditLog[].ragResponse

​agentAuditLog[].mcpToolCalls[]

​findings[] — Hallazgos de verificación

​recommendations[] — Recomendaciones

​targetItems[] — Items objetivo

​Enumeraciones de estado

Endpoint

Solicitud

Query Parameters

Estructura de la respuesta

Campos de nivel superior

`riskAssessment` — Evaluación de riesgo

`systemMetadata` — Metadatos de ejecución

`systemMetadata.workflowHistory[]`

`extractedData` — Datos estructurados extraídos

`extractedData.review_result` — Resultado final de revisión

`extractedData.extracted_values` — Valores extraídos en bruto

`extractedData.category_judgements` — Juicios de verificación

`extractedData.document_validations` — Validez documental

`outputSchema` — Output schema enriquecido

Campos comunes en `outputSchema.properties`

`extractionStatus` — Estado de extracción de campos

`rawActionResults` — Resultados de acciones en bruto

`agentAuditLog[]` — Registro de auditoría del agente

`agentAuditLog[].ragResponse`

`agentAuditLog[].mcpToolCalls[]`

`findings[]` — Hallazgos de verificación

`recommendations[]` — Recomendaciones

`targetItems[]` — Items objetivo

Enumeraciones de estado