엔드포인트
GET /v1/analyses/{analysisId}
요청
경로 파라미터
| 파라미터 | 타입 | 설명 |
|---|---|---|
analysisId | string | 조회할 분석 ID (analysis_ 접두사) |
curl "https://client-omni-api.argosidentity.com/v1/analyses/analysis_lghgsxkorvoc" \
-H "x-api-key: your-api-key-here"
응답 구조
응답 필드는 두 갈래입니다.| 갈래 | 필드 | 성격 |
|---|---|---|
| 시스템 고정 | 아래 최상위 필드의 나머지 전부 | 워크플로우와 무관하게 항상 같은 키 |
| 출력 스키마 기반 | outputSchema · extractedData · extractionStatus | 키 이름과 중첩 구조가 워크플로우마다 다름 |
extractedData에 어떤 필드가 들어오는지는 워크플로우의 출력 스키마가 결정합니다. Omni가 공통 키를 강제하지 않습니다. 다만 말단 필드의 값은 항상 같은 모양의 봉투(value · reasoning · sourceStep)로 감싸집니다.최상위 필드
| 필드 | 타입 | 설명 |
|---|---|---|
id | string | 분석 ID (analysis_ 접두사) |
profileId | string | 소속 프로파일 ID |
folderId | string | null | 대상 폴더 ID. 프로파일 전체 분석이면 null |
engineId | string | null | 단일 엔진을 지정해 실행한 경우의 엔진 ID. 워크플로우 구성을 따르면 null |
engine | object | null | engineId가 있을 때의 엔진 상세. 그 외에는 null |
playbookId | string | 분석에 사용된 플레이북 ID (PB- 접두사) |
playbookVersion | string | null | 동결된 플레이북 버전. 동결본이 없으면 null |
capturedAt | string | null | 플레이북 동결 시각. 동결본이 없으면 null |
snapshotStatus | string | null | 동결 상태: frozen · legacy · missing |
playbookSnapshot | string | null | 실제로 실행한 플레이북 본문 |
status | string | 처리 상태: pending · processing · completed · failed |
processingTimeMs | number | 처리 소요 시간(밀리초) |
verificationStatus | string | 분석 전체 판정: verified · pending_review · rejected |
confidenceScore | number | null | 판정 신뢰도(0.0–1.0). confidence와는 다른 지표 |
confidence | object | Analysis Score. 아래 표 |
details | object[] | 점수 감점 사유 목록. 아래 표 |
riskAssessment | object | 위험도. 아래 표 |
systemMetadata | object | 실행 메타데이터. 아래 표 |
outputSchema | object | null | 실행 시점에 동결된 출력 스키마. 정의하지 않았으면 null |
extractedData | object | 추출 결과. 구조는 outputSchema를 따름 |
extractionStatus | object | deprecated. 하위 호환용 최상위 키 단위 맵 |
rawActionResults | object | 액션별 원시 결과. 아래 표 |
agentAuditLog | object | 단계별 실행 감사 로그. 아래 표 |
findings | object[] | 액션 결과 요약(UI 표시용). 아래 표 |
recommendations | object[] | 후속 조치 권고. 아래 표 |
targetItems | object[] | 분석에 참조된 아이템. 아래 표 |
error | object | null | 실패 시 code · message(선택 details). 정상이면 null |
options | object | null | 요청 시 전달한 옵션. 없으면 null |
clientMetadata | object | null | 요청 시 전달한 클라이언트 메타데이터. 없으면 null |
primaryReportId | string | null | 생성된 주 리포트 ID (rpt_ 접두사) |
reportId | string | null | primaryReportId와 같은 값의 레거시 필드. 신규 연동은 primaryReportId 사용 |
requestedAt | string | 요청 시각 |
completedAt | string | null | 완료 시각. 미완료면 null |
createdAt | string | 레코드 생성 시각 |
confidence 분석 점수
대시보드 분석 상세 최상단에 표시되는 점수입니다.
| 필드 | 타입 | 설명 |
|---|---|---|
components | object | 점수를 구성하는 세 항목. 측정할 수 없으면 null |
score | number | null | 세 항목의 가중 평균(0–100, 반올림) |
level | string | null | HIGH(80–100) · MEDIUM(65–79) · LOW(0–64) |
confidence.components
| 필드 | 가중치 | 설명 |
|---|---|---|
stepExecution | 40% | 플레이북에 정의된 단계 중 실제로 실행된 비율(0–100) |
stepQuality | 20% | 실행된 단계의 통과 상태와 엔진 호출 여부를 반영한 품질 점수(0–100) |
outputCompleteness | 40% | 출력 스키마 말단 필드 중 값이 채워진 비율(0–100). 배열은 원소마다 계산 |
score = round(stepExecution × 0.4 + stepQuality × 0.2 + outputCompleteness × 0.4)
null인 항목이 있으면 남은 항목의 가중치로 정규화합니다. 전부 null이면 score와 level도 null입니다.
details 감점 사유
confidence 점수를 낮춘 항목을 개별로 나열합니다. 감점 요인이 없으면 빈 배열입니다.
| 필드 | 타입 | 설명 |
|---|---|---|
category | string | STEP · JSON_OUTPUT · TOOL |
type | string | 세부 유형(아래 표) |
target | string | 대상. 액션명 또는 출력 스키마 말단 필드의 인스턴스 경로 |
reasonCode | string | (선택) 값이 채워지지 않은 이유. JSON_OUTPUT 항목에만 |
message | string | (선택) 담당 단계가 남긴 판단 근거. JSON_OUTPUT 항목에만 |
stepId | number | (선택) 담당 단계의 agentAuditLog.steps[].step. JSON_OUTPUT 항목에만 |
type | category | 의미 |
|---|---|---|
STEP_NEED_REVIEW | STEP | 단계가 수동 검토 필요로 종료 |
STEP_FAILED | STEP | 단계가 실패로 종료 |
STEP_NOT_EXECUTED | STEP | 플레이북에 정의됐으나 실행되지 않음 |
TOOL_NOT_EXECUTED | TOOL | 설정됐으나 호출되지 않은 엔진 |
OUTPUT_MISSING | JSON_OUTPUT | 출력 스키마 필드에 값이 채워지지 않음 |
OUTPUT_EMPTY | JSON_OUTPUT | 필드는 있으나 값이 비어 있음 |
reasonCode는 확장 가능한 열거형입니다. 현재 값과 해석 방법은 분석 결과 읽기를 참조하세요.
riskAssessment
| 필드 | 타입 | 설명 |
|---|---|---|
riskLevel | string | low(0–25) · medium(26–50) · high(51–75) · critical(76–100) |
riskScore | number | 위험 점수(0–100, 높을수록 위험) |
riskFactors | string[] | 점수 상승 요인. 없으면 빈 배열 |
riskScore 산정
액션 단위 판정 결과만으로 계산됩니다. 문서 내용이나 추출 결과는 반영되지 않습니다.riskScore = min(100, 25 + 실패한_액션수 × 20 + 검토필요_액션수 × 10)
기본값이 25이므로
riskScore는 25보다 낮아질 수 없습니다. 모든 액션이 통과하면 정확히 25(low)입니다. 표의 low 범위가 0–25인 것은 등급 경계일 뿐, 실제로 0–24가 나오지는 않습니다.| 액션 결과 | riskScore | riskLevel |
|---|---|---|
| 전부 통과 | 25 | low |
| 검토 필요 1개 | 35 | medium |
| 실패 1개 | 45 | medium |
| 실패 2개 | 65 | high |
| 실패 4개 이상 | 100 | critical |
riskFactors에는 실패한 액션마다 {액션명} verification failed가, 검토 필요 액션이 있으면 {개수} action(s) need manual review가 한 줄로 들어갑니다.
systemMetadata
systemMetadata.outputFormatting
| 필드 | 타입 | 설명 |
|---|---|---|
status | string | skipped · formatted · validation_failed · fallback_raw |
error | string | null | 조립 실패 사유. 그 외에는 null |
ajvErrors | string[] | JSON Schema 검증 불일치 목록. 없으면 빈 배열 |
status | 의미 | extractedData의 모양 |
|---|---|---|
skipped | 출력 스키마 없음 | 액션명 키 구조(봉투 없음) |
formatted | 정상 조립 | 출력 스키마 구조 + 봉투 |
validation_failed | 조립됐으나 스키마 검증 불일치 | 출력 스키마 구조 + 봉투 |
fallback_raw | 조립 실패로 원본 구조 폴백 | 액션명 키 구조(봉투 없음) |
extractedData를 읽기 전에 이 status부터 분기해야 합니다. 분기 방법은 분석 결과 읽기에 있습니다.systemMetadata.workflowHistory
실행된 작업만 포함됩니다. 전체 단계 정의는 GET /workflows/:workflowId의 workflowActions에 있습니다.
| 필드 | 타입 | 설명 |
|---|---|---|
workId | number | 작업 순번(1부터) |
actionName | string | 실행된 액션 함수명 |
actionDescription | string | 액션 설명 |
query | string | 에이전트가 사용한 쿼리·지시문 |
reason | string | 결과에 대한 판단 근거 |
success | boolean | 작업 성공 여부 |
verificationStatus | string | 액션 단위 판정: passed · needs_review · failed |
iteration | number | 완료 시점의 반복 번호 |
timestamp | string | 완료 시각 |
systemMetadata.tokenUsage
| 필드 | 타입 | 설명 |
|---|---|---|
totalTokens | number | 총 토큰 수 |
promptTokens | number | 입력 토큰 수 |
completionTokens | number | 출력 토큰 수 |
tokenUsagePerWorkId는 작업 ID를 키로, 위와 같은 구조를 값으로 갖습니다.
rawActionResults
액션이 반환한 조립 전 원시 결과입니다. 키는 액션명이며, 어떤 액션이 있는지는 워크플로우의 workflowActions 정의를 따릅니다.
| 필드 | 타입 | 설명 |
|---|---|---|
answer | string | 액션 실행 결과 텍스트 |
workId | number | 작업 순번 |
confidence | number | 결과 신뢰도(0.0–1.0) |
citationsCount | number | 답변에 사용된 인용 청크 수 |
verificationStatus | string | passed · needs_review · failed |
mcpResults | object[] | (선택) 외부 엔진 호출 결과. 호출이 없으면 필드 자체가 생략 |
error | object | (선택) 액션 실행 중 에러. 없으면 생략 |
rawActionResults.{actionName}.mcpResults[]
agentAuditLog.steps[].mcpcalls[]와 같은 호출을 액션 기준으로 정리한 목록입니다. 최상위와 같은 카멜 케이스를 씁니다.
| 필드 | 타입 | 설명 |
|---|---|---|
tool | string | 호출된 도구 식별자 |
engine | string | null | 엔진 표시 이름 |
purpose | string | null | 호출 이유 |
input | object | null | 전달한 입력값 |
success | boolean | 호출 성공 여부 |
result | object | null | 도구가 반환한 원시 응답. 구조는 엔진마다 다름 |
durationMs | number | null | 소요 시간(밀리초) |
errorCode | string | null | 실패 시 에러 코드(예: MCP_TIMEOUT) |
errorType | string | null | 실패 시 에러 유형 |
errorMessage | string | null | 실패 시 에러 메시지 |
fallbackToRag | boolean | 엔진 실패 후 문서 검색으로 대체 실행했는지 |
agentAuditLog
steps와 summary 두 키를 가진 객체입니다.
agentAuditLog는 배열이 아니라 객체이고, 내부 필드는 스네이크 케이스(work_id · executed_at · duration_ms)를 씁니다. 최상위 필드의 카멜 케이스와 표기 규칙이 다릅니다.agentAuditLog.steps
| 필드 | 타입 | 설명 |
|---|---|---|
step | number | 실행 순서(1부터). 워크플로우를 수정하면 번호가 바뀔 수 있음 |
work_id | number | null | 플레이북 액션의 고정 식별자. workflowActions[].workId와 대응 |
action | string | 실행된 액션명 |
rule | string | 해당 단계가 수행한 지시 |
status | string | passed · needs_review · failed |
category | string | DOCUMENT · IDENTITY · COMPLIANCE · FINANCIAL · OTHER. 미분류는 빈 문자열 |
tokens | number | 해당 단계의 토큰 사용량 |
item_ids | string[] | 참조한 아이템 ID 목록 |
mcpcalls | object[] | 외부 엔진 호출 내역. 없으면 빈 배열 |
reasoning | string | 판단 근거 |
executed_at | string | 실행 시각 |
agentAuditLog.steps[].mcpcalls[]
| 필드 | 타입 | 설명 |
|---|---|---|
tool | string | 호출된 도구 식별자 |
engine | string | 엔진 표시 이름 |
input | object | 전달한 입력값 |
result | object | 도구가 반환한 원시 응답. 구조는 엔진마다 다름 |
purpose | string | 호출 이유 |
duration_ms | number | 소요 시간(밀리초) |
success | boolean | 호출 성공 여부 |
fallback_to_rag | boolean | 엔진 실패 후 문서 검색으로 대체 실행했는지 |
error_code | string | (실패 시) 에러 코드 |
error_type | string | (실패 시) 에러 유형 |
error_message | string | (실패 시) 에러 메시지 |
agentAuditLog.summary
| 필드 | 타입 | 설명 |
|---|---|---|
total_steps | number | 실행된 총 단계 수 |
passed | number | passed로 종료된 단계 수 |
needs_review | number | needs_review로 종료된 단계 수 |
failed | number | failed로 종료된 단계 수 |
total_tokens | number | 분석 전체 토큰 사용량 |
overall_decision | string | 단계 결과 집계: passed · needs_review · failed |
started_at | string | 첫 단계 시작 시각 |
ended_at | string | 마지막 단계 종료 시각 |
subject | object | 분석 대상 요약 |
findings
| 필드 | 타입 | 설명 |
|---|---|---|
id | string | 항목 ID (af_ 접두사) |
category | string | 액션명과 동일 |
result | string | passed · warning · failed |
confidence | number | 신뢰도(0.0–1.0) |
details | string | 결과 상세(일부 잘릴 수 있음) |
sortOrder | number | 표시 순서 |
result는 agentAuditLog.steps[].status를 UI용으로 바꾼 값입니다(needs_review → warning).
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 | 소스 참조 정보 |
응답 예시
실제 응답은 훨씬 깁니다. 아래 예시는 최상위 키를 모두 담되, 배열·중첩 객체는 대표 항목 하나씩만 실었습니다.{
"id": "analysis_lghgsxkorvoc",
"profileId": "pf_0twd91ioowfr",
"folderId": null,
"engineId": null,
"engine": null,
"playbookId": "PB-20260910-FWP24I",
"playbookVersion": "1.0.0",
"capturedAt": "2026-09-09T09:11:04.220Z",
"snapshotStatus": "frozen",
"playbookSnapshot": "---\nname: playbook.md\ndescription: 거래처 온보딩 서류 검증\n---\n...",
"status": "completed",
"processingTimeMs": 132480,
"verificationStatus": "verified",
"confidenceScore": 0.92,
"confidence": {
"components": { "stepExecution": 100, "stepQuality": 85, "outputCompleteness": 90 },
"score": 93,
"level": "HIGH"
},
"details": [
{
"category": "JSON_OUTPUT", "type": "OUTPUT_MISSING", "target": "bank_account.bank_name",
"reasonCode": "NOT_IN_FINAL_OUTPUT", "stepId": 2,
"message": "통장 사본에서 예금주는 확인했으나 은행명 항목이 최종 출력에 포함되지 않았습니다."
}
],
"riskAssessment": { "riskLevel": "low", "riskScore": 25, "riskFactors": [] },
"systemMetadata": {
"totalIterations": 7,
"completedWorkIds": [1, 2, 3, 4, 5],
"workflowHistory": [
{
"workId": 1, "actionName": "verify_document_presence", "iteration": 1,
"actionDescription": "3종 서류(사업자등록증, 통장사본, 실소유자확인서) 제출 여부 확인",
"query": "제출된 서류 목록에 3종이 모두 있는지 판단",
"reason": "3종 서류가 모두 제출되어 있습니다.",
"success": true, "verificationStatus": "passed",
"timestamp": "2026-09-09T09:11:36.114Z"
}
],
"tokenUsage": { "totalTokens": 48210, "promptTokens": 45880, "completionTokens": 2330 },
"tokenUsagePerWorkId": {
"1": { "totalTokens": 12480, "promptTokens": 11902, "completionTokens": 578 }
},
"outputFormatting": { "status": "formatted", "error": null, "ajvErrors": [] }
},
"outputSchema": {
"type": "object",
"properties": {
"company": {
"type": "object",
"properties": { "name": { "type": "string", "description": "상호(법인명)" } }
},
"documents_complete": { "type": "boolean", "description": "필수 서류 3종 제출 여부" }
}
},
"extractedData": {
"company": {
"name": {
"value": "주식회사 에이씨엠이 트레이딩", "sourceStep": 1,
"reasoning": "사업자등록증의 법인명 항목에서 확인했습니다."
}
},
"documents_complete": {
"value": true, "sourceStep": 1,
"reasoning": "3종 서류가 모두 제출되었습니다."
}
},
"extractionStatus": { "company": "extracted", "documents_complete": "extracted" },
"rawActionResults": {
"execute_aml_screening": {
"answer": "대표자 홍길동에 대한 AML·제재 목록 조회 결과 일치 항목이 없습니다.",
"workId": 5, "confidence": 0.9, "citationsCount": 1, "verificationStatus": "passed",
"mcpResults": [
{
"tool": "aml_search_person", "engine": "AML Search - Person",
"purpose": "대표자 성명으로 제재 목록을 조회",
"input": { "name": "홍길동" },
"success": true, "result": { "matches": [], "status": "No Matches" },
"durationMs": 1840, "fallbackToRag": false,
"errorCode": null, "errorType": null, "errorMessage": null
}
]
}
},
"agentAuditLog": {
"steps": [
{
"step": 1, "work_id": 1, "action": "verify_document_presence",
"rule": "3종 서류(사업자등록증, 통장사본, 실소유자확인서) 제출 여부 확인",
"status": "passed", "category": "DOCUMENT", "tokens": 12480,
"item_ids": ["item_ieoravdq3jp3", "item_we03t42pxgbc", "item_veliji1hm3ih"],
"mcpcalls": [],
"reasoning": "3종 서류가 모두 제출되어 있어 통과로 판정했습니다.",
"executed_at": "2026-09-09T09:11:36.114Z"
}
],
"summary": {
"total_steps": 5, "passed": 5, "needs_review": 0, "failed": 0,
"total_tokens": 48210, "overall_decision": "passed",
"started_at": "2026-09-09T09:11:05.900Z", "ended_at": "2026-09-09T09:13:16.700Z",
"subject": { "name": "예시 프로파일", "type": "business" }
}
},
"findings": [
{
"id": "af_2k9x4m7p1q3z", "category": "verify_document_presence",
"result": "passed", "confidence": 0.95, "sortOrder": 1,
"details": "사업자등록증·통장 사본·실소유자 확인서 3종이 모두 확인되었습니다."
}
],
"recommendations": [
{
"id": "ar_5b8n2v6c9k1d", "priority": 2, "sortOrder": 1,
"content": "통장 사본의 은행명이 추출되지 않았습니다. 원본 이미지 품질을 확인하세요."
}
],
"targetItems": [
{ "itemId": "item_ieoravdq3jp3", "name": "사업자등록증", "type": "text", "sourceRef": null }
],
"error": null,
"options": null,
"clientMetadata": null,
"primaryReportId": "rpt_7h3k9m1x5p8t",
"reportId": "rpt_7h3k9m1x5p8t",
"requestedAt": "2026-09-09T09:11:04.220Z",
"completedAt": "2026-09-09T09:13:16.700Z",
"createdAt": "2026-09-09T09:13:16.700Z"
}
상태값 열거형 요약
- status
- verificationStatus
- 단계 결과
- findings result
- riskLevel
- outputFormatting.status
- reasonCode
- snapshotStatus
| 값 | 설명 |
|---|---|
pending | 분석 대기 중 |
processing | 분석 진행 중 |
completed | 분석 완료 |
failed | 분석 실패 |
분석 전체에 대한 시스템 판정입니다.
| 값 | 설명 |
|---|---|
verified | 모든 단계 통과 |
pending_review | 수동 검토가 필요한 단계 존재 |
rejected | 실패한 단계 존재 |
액션 단위 결과입니다.
agentAuditLog.summary.overall_decision도 같은 값 집합을 씁니다.| 값 | 설명 |
|---|---|
passed | 검증 통과 |
needs_review | 수동 검토 필요 |
failed | 검증 실패 |
| 값 | 설명 |
|---|---|
passed | 정상 |
warning | 경고(검토 필요) |
failed | 실패 |
| 값 | 설명 |
|---|---|
low | 저위험(0–25) |
medium | 중위험(26–50) |
high | 고위험(51–75) |
critical | 심각(76–100) |
| 값 | 설명 |
|---|---|
skipped | 출력 스키마 없음 — extractedData는 액션명 키 구조 |
formatted | 정상 조립 |
validation_failed | 조립됐으나 스키마 검증 불일치(ajvErrors 참고) |
fallback_raw | 조립 실패로 원본 구조 반환 — extractedData는 액션명 키 구조 |
확장 가능한 열거형입니다. 표에 없는 값도 허용하도록 구현하세요.
| 값 | 설명 |
|---|---|
PARENT_MISSING | 상위 항목 부재로 하위 항목 미산출 |
EMPTY_VALUE | 키는 있으나 값이 비어 있음 |
NOT_IN_FINAL_OUTPUT | 최종 출력에 항목이 포함되지 않음 |
TOOL_ERROR | 담당 단계의 외부 엔진 호출 실패 |
| 값 | 설명 |
|---|---|
frozen | 실행 시점 동결본 있음 |
legacy | 동결 기능 도입 전 분석 — 현재 플레이북으로 대체 |
missing | 동결본 없음 — 현재 플레이북으로 대체 |
에러 코드
| 상태 | 코드 | 설명 |
|---|---|---|
| 404 | OMNI_3004 | 분석을 찾을 수 없음 |