---
title: 작업 API
description: 작업을 조회하고 상태 변경을 스트리밍하며, 취소 가능한 작업을 취소하고 결과 링크를 재발급합니다.
species: reference
---
# 작업 API

작업은 비동기 처리의 영구 기록입니다. 쿼리 작업은 공개 상태 `queued`, `running`, `succeeded`, `failed`, `cancelled`를 제공합니다.

## 작업 목록 조회

```endpoint
GET /jobs
```

최신 작업부터 반환합니다. `limit`의 기본값은 20이며 1~100을 지정할 수 있습니다. `has_more`가 true이면 `next_cursor`를 `starting_after`로 전달하세요.

## 작업 하나 조회

```endpoint
GET /jobs/{id}
```

현재 상태, 타임스탬프, 종류, 실패 정보를 반환합니다. `404 job_not_found`는 알 수 없는 ID와 다른 조직의 작업을 구분하지 않습니다.

## 이벤트 추적

```endpoint
GET /jobs/{id}/events
```

이 Server-Sent Events 스트림은 각 데이터 이벤트에 안정적으로 증가하는 `id`를 부여합니다. `Last-Event-ID`로 다시 연결하세요. 스트림은 재시도 간격을 5초로 알리고, 3초마다 영구 저장된 상태를 확인하며, 25초마다 하트비트 주석을 보냅니다.

연결은 웹 계층의 120초 한도 직전에 닫힙니다. 다시 연결하고, 최종 상태의 기준으로 항상 `GET /jobs/{id}`를 사용하세요. 유효하지 않은 이벤트 ID는 `400 invalid_last_event_id`를 반환합니다.

## 결과 가져오기

```endpoint
GET /jobs/{id}/result
```

성공한 쿼리 작업의 경우 1시간 동안 유효한 새 서명된 Parquet URL을 반환합니다. 이 URL은 데이터 접근 권한이 있는 비밀 정보로 취급하세요.

## 취소

```endpoint
POST /jobs/{id}/cancel
```

대기 중인 작업은 원자적으로 취소됩니다. 실행 중인 쿼리는 가능한 범위에서 취소합니다. 엔진에서 이미 수락한 작업은 끝까지 실행될 수 있으므로 `execution_may_continue: true`를 반환할 수 있습니다. 최종 상태는 작업을 폴링하여 확인하세요.

`GET /version`은 응답 헤더에 표시되는 공개 API 계약 버전을 반환합니다.