GET /analyses/:analysisId

엔드포인트

GET /v1/analyses/{analysisId}

요청

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

쿼리 파라미터

파라미터	타입	필수	기본값	설명
`waitForReport`	`boolean`		`false`	리포트 생성을 대기합니다 (롱 폴링)
`timeoutSeconds`	`number`		`120`	최대 대기 시간 (초 단위, 10–300)

waitForReport를 true로 설정하면, 리포트가 생성되거나 timeoutSeconds 임계값에 도달할 때까지 연결을 유지합니다. 분석 완료 직후 리포트가 즉시 필요한 동기식 워크플로우에 유용합니다.

응답 구조

분석 응답은 워크플로우 설정과 관계없이 항상 존재하는 고정 뼈대(최상위 필드, 위험도 평가, 시스템 메타데이터, 검증 결과 등)를 가집니다.

extractedData와 outputSchema 섹션은 워크플로우의 출력 스키마 설정에 따라 결정됩니다. 내부 필드는 출력 스키마를 어떻게 정의했느냐에 따라 달라집니다. 아래 예시는 KYB 검증 워크플로우 기준이며, 실제 결과는 설정한 스키마에 따라 다른 필드를 가집니다.

최상위 필드

모든 분석 응답에 항상 존재하는 필드입니다.

string

필수

분석 고유 ID (analysis_ 접두사)

profileId

string

필수

이 분석이 속한 프로필 ID

folderId

string | null

필수

분석 대상 폴더 ID (전체 프로필 분석 시 null)

engineId

string | null

필수

사용된 엔진 ID (기본 엔진 사용 시 null)

playbookId

string

필수

분석에 사용된 플레이북 ID (PB- 접두사)

engine

object | null

필수

엔진 상세 정보 (기본 엔진 사용 시 null)

status

string

필수

분석 상태: pending / processing / completed / failed

processingTimeMs

number

필수

분석 처리 소요 시간 (밀리초)

verificationStatus

string

필수

최종 검증 상태: pending_review / approved / rejected

error

string | null

필수

에러 메시지 (정상 완료 시 null)

options

object | null

분석 요청 시 전달된 옵션

clientMetadata

object | null

클라이언트가 분석 요청 시 전달한 메타데이터

primaryReportId

string | null

이 분석에 대해 생성된 주 리포트 ID (rpt_ 접두사)

requestedAt

string

필수

분석 요청 시각 (ISO 8601)

completedAt

string | null

필수

분석 완료 시각 (ISO 8601, 미완료 시 null)

createdAt

string

필수

DB 레코드 생성 시각 (ISO 8601)

`riskAssessment` — 위험도 평가

AI 에이전트가 모든 검증 단계를 종합하여 산정한 최종 위험도입니다.

필드	타입	설명
`riskLevel`	`string`	위험 등급: `low` / `medium` / `high`
`riskScore`	`number`	위험 점수 (0–100, 높을수록 위험)
`riskFactors`	`string[]`	위험 등급 상승에 기여한 요인 목록

`systemMetadata` — 시스템 실행 메타데이터

AI 에이전트가 분석을 수행하는 동안의 내부 실행 정보입니다.

필드	타입	설명
`totalIterations`	`number`	에이전트가 수행한 총 반복(iteration) 횟수
`completedWorkIds`	`number[]`	성공적으로 완료된 작업(Work) ID 목록
`workflowHistory`	`object[]`	각 작업의 실행 요약 히스토리

`systemMetadata.workflowHistory[]`

필드	타입	설명
`workId`	`number`	작업 순번 (1부터 시작)
`actionName`	`string`	실행된 액션 함수명
`query`	`string`	에이전트가 해당 작업에 사용한 쿼리/지시문
`reason`	`string`	작업 결과에 대한 에이전트의 판단 근거
`success`	`boolean`	작업 성공 여부
`iteration`	`number`	해당 작업이 완료된 시점의 반복 번호
`timestamp`	`string`	작업 완료 시각 (ISO 8601)

`extractedData` — 추출된 구조화 데이터

이 섹션은 동적입니다. extractedData 내부의 필드는 워크플로우에서 정의한 출력 스키마에 따라 결정됩니다. 아래 예시는 사업자등록 검증이 포함된 KYB 워크플로우 기준이며, 실제 필드는 다를 수 있습니다.

AI가 문서에서 추출하고 분석하여 출력 스키마 형식에 맞게 구조화한 최종 데이터입니다.

`extractedData.review_result` — 최종 검토 결과

필드	타입	설명
`final_action`	`string`	최종 처리 방향: `approve` / `reject` / `manual_review`
`final_risk_level`	`string`	최종 위험 등급: `low` / `medium` / `high`
`final_action_reason`	`string`	최종 처리 방향 결정 근거
`final_risk_level_reason`	`string`	최종 위험 등급 결정 근거

`extractedData.extracted_values` — 문서 추출 원시 값

제출된 문서에서 직접 추출한 값입니다. 필드는 출력 스키마 정의에 따라 달라집니다. 예시 (사업자등록 KYB):

필드	타입	설명
`brc_business_name`	`string`	사업자등록증의 법인명(상호)
`brc_business_registration_number`	`string`	사업자등록증의 사업자등록번호
`brc_corporate_registration_number`	`string`	사업자등록증의 법인등록번호
`brc_representative_name`	`string`	사업자등록증의 대표자명
`brc_address`	`string`	사업자등록증의 사업장 소재지
`brc_opening_date`	`string`	사업자등록증의 개업일자
`brc_issue_date`	`string`	사업자등록증의 발급일자

`extractedData.category_judgements` — 카테고리별 검증 판단

카테고리별 검증 결과와 통과/실패 상태 및 판단 근거입니다.

필드	타입	설명
`{field}_check_result`	`string`	검증 결과: `pass` / `fail` / `unverifiable` / `needs_review`
`{field}_check_reason`	`string`	검증 판단 근거
`overall_consistency_result`	`string`	전체 일치성: `pass` / `needs_review` / `fail`
`overall_consistency_reason`	`string`	전체 일치성 판단 근거

`extractedData.document_validations` — 문서 유효성 검증

필드	타입	설명
`{document}_is_valid`	`boolean`	문서 유효성 여부
`{document}_is_valid_reason`	`string`	유효성 판단 근거

`outputSchema` — 워크플로우 출력 스키마 (Enriched)

extractedData와 동일한 데이터를 담고 있으며, 워크플로우의 JSON Schema에 실제 값이 채워진 형태입니다. extractedData를 정식 사용 필드로 이용하세요.

`outputSchema.properties` 내 공통 필드 구조

필드	타입	설명
`request_id`	`string`	요청 식별자 (프로필 ID와 동일)
`policy_flags`	`string[]`	정책 위반/주의 사항 플래그 목록
`review_result`	`object`	최종 검토 결과
`extracted_values`	`object`	문서에서 추출한 원시 값
`category_judgements`	`object`	카테고리별 검증 판단 결과
`document_validations`	`object`	문서별 유효성 검증 결과
`recommended_next_steps`	`string[]`	AI가 권고하는 후속 조치 목록

`extractionStatus` — 필드별 추출 상태

각 출력 스키마 최상위 필드가 성공적으로 추출되었는지 나타내는 상태 맵입니다.

값	의미
`"extracted"`	해당 필드 추출/생성 성공
`"missing"`	해당 필드 추출 실패 (문서 없음 또는 정보 부재)

`rawActionResults` — 액션별 원시 결과

각 AI 액션이 반환한 원시 결과 데이터입니다. 키는 actionName입니다.

필드	타입	설명
`answer`	`string`	액션 실행 결과 텍스트 (RAG 응답 또는 LLM 생성 내용)
`workId`	`number`	해당 작업의 순번
`citationsCount`	`number`	답변 생성에 사용된 인용 청크 수
`verificationStatus`	`string`	검증 결과: `passed` / `needs_review` / `failed`

`agentAuditLog[]` — 에이전트 실행 감사 로그

AI 에이전트가 분석 과정에서 수행한 모든 단계의 상세 실행 로그입니다. rawActionResults보다 세부적이며 MCP 도구 호출 정보도 포함합니다.

필드	타입	설명
`workId`	`number`	작업 순번
`actionName`	`string`	실행된 액션명
`category`	`string`	액션 카테고리. 예: `Document Classification`, `Data Extraction`, `Format Validation`, `Status Validation`, `Data Consistency`, `Document Processing`, `mcp`(외부 도구) 등이며, 워크플로 정책에 따라 달라질 수 있습니다.
`query`	`string`	에이전트가 전달한 쿼리 또는 지시문
`reasoning`	`string`	에이전트의 판단 근거 (없을 수 있음)
`success`	`boolean`	실행 성공 여부
`iteration`	`number`	해당 로그가 기록된 반복 번호
`durationMs`	`number`	액션 실행 소요 시간 (밀리초)
`executedAt`	`string`	실행 시각 (ISO 8601)
`verificationStatus`	`string	null`	단계별 검증 결과가 있을 때의 값(예: `passed` / `needs_review` / `failed`). MCP 전용 단계 등 pass/fail이 없는 작업에서는 생략될 수 있습니다.
`targetItemIds`	`string[]`	이 액션이 참조한 아이템 ID 목록
`ragResponse`	`object	null`	RAG 조회를 수행한 경우 조회 결과
`mcpToolCalls`	`object[]	null`	MCP 도구를 호출한 경우 호출 상세 정보

`agentAuditLog[].ragResponse`

RAG 조회를 수행한 액션에만 존재합니다.

필드	타입	설명
`answer`	`string`	RAG가 생성한 응답 텍스트
`citations`	`object[]`	응답 생성에 사용된 인용 청크 목록
`chunksSearched`	`number`	검색된 청크 수
`processingTimeMs`	`number`	RAG 처리 소요 시간 (밀리초)

`agentAuditLog[].mcpToolCalls[]`

MCP 외부 도구를 호출한 액션에만 존재합니다 (예: AML 스크리닝).

필드	타입	설명
`toolName`	`string`	호출된 MCP 도구명 (예: `search_individual`)
`engineCode`	`string`	해당 도구에 매핑된 엔진 식별자 (예: `aml-search`)
`engineName`	`string`	엔진 표시 이름 (예: `AML Search - Person`)
`params`	`object`	도구 호출 파라미터
`success`	`boolean`	호출 성공 여부
`startedAt`	`string`	호출 시작 시각 (ISO 8601)
`executionTimeMs`	`number`	도구 호출 소요 시간 (밀리초)
`rawContent`	`object`	도구가 반환한 원시 응답 데이터
`fallbackToRag`	`boolean`	MCP 실패 시 RAG로 폴백했는지 여부
`selectionReason`	`string`	해당 도구를 선택한 에이전트의 이유

`findings[]` — 검증 결과 항목

각 액션의 결과를 정렬된 형태로 요약한 목록입니다. UI 표시용입니다.

필드	타입	설명
`id`	`string`	결과 항목 고유 ID (`af_` 접두사)
`category`	`string`	카테고리 (액션명과 동일)
`result`	`string`	결과: `passed` / `warning` / `failed`
`details`	`string`	결과 상세 내용 (일부 잘릴 수 있음)
`sortOrder`	`number`	표시 순서

`recommendations[]` — 권고사항

시스템이 생성한 후속 조치 권고사항 목록입니다.

필드	타입	설명
`id`	`string`	권고사항 고유 ID (`ar_` 접두사)
`content`	`string`	권고사항 내용
`priority`	`number`	우선순위 (낮을수록 높은 우선순위)
`sortOrder`	`number`	표시 순서

`targetItems[]` — 분석 대상 아이템

이 분석에서 참조된 아이템 목록입니다.

필드	타입	설명
`itemId`	`string`	아이템 고유 ID (`item_` 접두사)
`name`	`string`	아이템 이름
`type`	`string`	아이템 타입: `file` / `text` / `json`
`sourceRef`	`string	null`	소스 참조 정보

상태값 열거형 요약

분석 상태 (status)
검증 상태 (verificationStatus)
위험 등급 (riskLevel)
검증 결과 (finding result)
검증 판단 (check_result)

값	설명
`pending`	분석 대기 중
`processing`	분석 진행 중
`completed`	분석 완료
`failed`	분석 실패

값	설명
`pending_review`	수동 검토 필요
`approved`	승인됨
`rejected`	거부됨

값	설명
`low`	저위험
`medium`	중위험
`high`	고위험

값	설명
`passed`	정상
`warning`	경고 (검토 필요)
`failed`	실패

값	설명
`pass`	일치 확인됨
`fail`	불일치
`unverifiable`	문서 부재로 검증 불가
`needs_review`	추가 검토 필요

개요

API 참조

엔드포인트

요청

쿼리 파라미터

응답 구조

최상위 필드

`riskAssessment` — 위험도 평가

`systemMetadata` — 시스템 실행 메타데이터

`systemMetadata.workflowHistory[]`

`extractedData` — 추출된 구조화 데이터

`extractedData.review_result` — 최종 검토 결과

`extractedData.extracted_values` — 문서 추출 원시 값

`extractedData.category_judgements` — 카테고리별 검증 판단

`extractedData.document_validations` — 문서 유효성 검증

`outputSchema` — 워크플로우 출력 스키마 (Enriched)

`outputSchema.properties` 내 공통 필드 구조

`extractionStatus` — 필드별 추출 상태

`rawActionResults` — 액션별 원시 결과

`agentAuditLog[]` — 에이전트 실행 감사 로그

`agentAuditLog[].ragResponse`

`agentAuditLog[].mcpToolCalls[]`

`findings[]` — 검증 결과 항목

`recommendations[]` — 권고사항

`targetItems[]` — 분석 대상 아이템

상태값 열거형 요약

개요

API 참조

​엔드포인트

​요청

​쿼리 파라미터

​응답 구조

​최상위 필드

​riskAssessment — 위험도 평가

​systemMetadata — 시스템 실행 메타데이터

​systemMetadata.workflowHistory[]

​extractedData — 추출된 구조화 데이터

​extractedData.review_result — 최종 검토 결과

​extractedData.extracted_values — 문서 추출 원시 값

​extractedData.category_judgements — 카테고리별 검증 판단

​extractedData.document_validations — 문서 유효성 검증

​outputSchema — 워크플로우 출력 스키마 (Enriched)

​outputSchema.properties 내 공통 필드 구조

​extractionStatus — 필드별 추출 상태

​rawActionResults — 액션별 원시 결과

​agentAuditLog[] — 에이전트 실행 감사 로그

​agentAuditLog[].ragResponse

​agentAuditLog[].mcpToolCalls[]

​findings[] — 검증 결과 항목

​recommendations[] — 권고사항

​targetItems[] — 분석 대상 아이템

​상태값 열거형 요약

엔드포인트

요청

쿼리 파라미터

응답 구조

최상위 필드

`riskAssessment` — 위험도 평가

`systemMetadata` — 시스템 실행 메타데이터

`systemMetadata.workflowHistory[]`

`extractedData` — 추출된 구조화 데이터

`extractedData.review_result` — 최종 검토 결과

`extractedData.extracted_values` — 문서 추출 원시 값

`extractedData.category_judgements` — 카테고리별 검증 판단

`extractedData.document_validations` — 문서 유효성 검증

`outputSchema` — 워크플로우 출력 스키마 (Enriched)

`outputSchema.properties` 내 공통 필드 구조

`extractionStatus` — 필드별 추출 상태

`rawActionResults` — 액션별 원시 결과

`agentAuditLog[]` — 에이전트 실행 감사 로그

`agentAuditLog[].ragResponse`

`agentAuditLog[].mcpToolCalls[]`

`findings[]` — 검증 결과 항목

`recommendations[]` — 권고사항

`targetItems[]` — 분석 대상 아이템

상태값 열거형 요약