---
title: "작업 상태 조회"
method: GET
path: "/v1/jobs/{job_id}"
tags: ["UnifiedJob"]
---

# 작업 상태 조회

`GET /v1/jobs/{job_id}`

## Request

- Base URL: `https://api.xdata.kr` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xdata.kr/v1/jobs/{job_id}`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://api.xdata.kr/oauth/authorize`, token URL `https://api.xdata.kr/oauth/token`)

`GET /v1/jobs/{job_id}` 작업 상태 조회.

응답 분기:
    - 작업 발견 (정책 통과 + 동일 org/env)  → 200 OK + 응답 10필드
    - 잡 부재 (또는 다른 org/env)            → 404 JOB_NOT_FOUND (정보 노출 차단)
    - 정책 거부 (AuthPolicyError)            → 401/402/403/422/429
    - PrincipalContext.organization_id None → 400 VALIDATION_INVALID_FIELD
        (데이터 손상 운영 진단 — 외부 silent 500 fallback 차단)
    - 잘못된 job_id 형식                     → 400 VALIDATION_INVALID_FIELD
    - 그 외 예외                             → 500 INTERNAL_ERROR

## Path parameters

- `job_id` string, required

## Query parameters

- `env_scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Headers

- `Authorization` string, nullable
- `X-Env-Scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Response `200`

Successful Response

- JobReadResponse: `GET /v1/jobs/{job_id}` 응답.
  - `job_id` string, required
  - `status` string, required: QUEUED · RUNNING · SUCCEEDED · FAILED · TIMEOUT 등.
  - `env_scope` string, required
  - `provider` string, required
  - `action` string, required
  - `submitted_at` string, required: KST ISO-8601.
  - `started_at` string, nullable: 시작 전이면 없다.
  - `finished_at` string, nullable: 끝나기 전이면 없다.
  - `retry_count` integer, required
  - `progress` integer, nullable: 0~100. 값과 문구는 MCP(SSE)와 같은 한 곳에서 온다(job_progress).
  - `progress_message` string, nullable: 지금 무엇을 하고 있는지 한국어 한 줄.
  - `retry_after_seconds` integer, nullable: 다음 조회까지 기다릴 초. 끝난 작업에는 없다.
  - `error` JobReadErrorEnvelope: 실패한 작업의 오류 봉투 - 표준 다섯 칸.
    - `code` string, required: 표준 오류 코드.
    - `message` string, nullable: 고객에게 보여 줄 한국어 설명.
    - `retryable` boolean, required: 다시 부를 만한 실패인가. **기관 쓰기 액션이면 코드와 무관하게 거짓**이다 - 이미 기관에 닿았을 수 있어 두 번째 요청이 또 나간다.
    - `provider_error_ref` string, nullable: 기관이 준 오류 식별자(있을 때만).
    - `upstream_status` integer, nullable: 기관 응답의 HTTP 상태(있을 때만).

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xdata/apis/xboss-api.md) · [All operations](https://skmtc.dev/xdata/apis/xboss-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xdata/apis/xboss-api/revisions/816de78950db?raw)