Skip to main content
POST
실행 시작
POST https://api-datahub.octoparse.com/v1/data-apps/{app_id}/runs 인증: API 키 필요(Authorization: Bearer <API Key>). 요청 본문은 App 입력 계약(App 상세의 input_schema)의 인스턴스 하나입니다. 검증은 엄격합니다. wait는 이 호출이 결과를 기다릴지 여부를 제어합니다:
  • 생략 시: App의 execution.mode 기본값을 따릅니다. sync App은 최종 상태까지 기다리고(App의 execution.timeout_seconds가 상한), async App은 즉시 run_id를 반환합니다.
  • 0–60 명시 시: 두 모드 모두 같게 동작하며 최대 wait초 동안 기다립니다. wait=0은 실행이 대기열에 들어가는 즉시 반환합니다. sync App이라도 먼저 run_id를 받은 뒤 Get a runwait으로 롱 폴링할 수 있습니다.
응답 시점에 이미 최종 상태에 도달했다면 sample_records에 첫 번째 배치가 포함될 수 있습니다. 전체 결과는 Get run records로 페이지를 넘기며 가져옵니다. version은 실행을 과거 Release에 고정합니다(계약과 가격은 해당 버전을 따름). build는 작성자 디버깅용으로, 변경할 수 없는 Build 스냅샷에 고정합니다(run_kind=test, 공개 통계에서 제외되지만 요금은 청구됨). versionbuild는 함께 지정할 수 없습니다. 실행 게이트는 상세 게이트와 같습니다: 보이지 않는 App은 404를 반환합니다. 보이지만 실행을 받지 않는 App은 403을 반환합니다(작성자의 자체 테스트는 제한 없음). yank된 버전에 고정한 새 실행은 거부됩니다(422).

요청

경로 파라미터

string
필수
App 참조: app_<hex> 또는 <namespace>/<app_name>.

쿼리 파라미터

number
최종 상태까지 기다리는 최대 초. 생략하면 App 모드의 기본값을 사용합니다. 0은 시작 직후 바로 반환합니다.범위 0~60.
integer
생성할 최대 레코드 수. 상한에 도달하면 실행이 정상 종료됩니다. 비용과 소요 시간을 제어하는 데 사용합니다.범위는 1 이상입니다.
string
기본값:"api"
채널 표시. 기본값은 api이며, SDK와 MCP는 각자의 값을 설정합니다. 실행 목록과 청구의 필터로 사용할 수 있습니다.
string
특정 버전에 고정합니다. 기본값은 최신 버전입니다.
string
작성자 디버그 전용. Build 스냅샷에 고정합니다. version과 함께 지정할 수 없습니다.

요청 body

App의 input_schema에 맞춘 JSON 객체. 가장 안전한 시작 방법은 App 상세의 examples에서 항목 하나를 복사해 수정하는 것입니다.

요청 예시

응답

200 성공

페이로드는 data로 감쌉니다. 필드:
string
필수
실행 ID. 상태 확인, 레코드 조회, 취소에 사용합니다.
string
게시자 사용자 이름.
string
App 이름.
string
고정된 버전. 디버그 실행은 null.
string
디버그 실행이 고정한 Build 스냅샷. 프로덕션 실행에서는 null.
string
일반은 production. 작성자 디버그는 test.
enum
필수
실행 상태. 값: PENDING / QUEUED / RUNNING / SUCCEEDED / PARTIALLY_SUCCEEDED / FAILED / CANCELLED / EXPIRED.
object
입력 에코. 입력 계약에서 sensitive로 표시된 필드는 마스킹됩니다.
object
진행 상황. done / total은 App이 보고하며, status_text는 App이 제공하는 사람이 읽을 수 있는 상태 문자열입니다.
string
결과 데이터셋 ID.
boolean
실행이 부분적으로 성공했거나 취소되면 true. 생성된 레코드는 계속 사용할 수 있습니다.
boolean
취소 요청 후 정리 중이면 true(협조 중지/부분 결과 회수). 종료 시 항상 false(서버 정규화). state에서 유도 불필요.
string
시작 채널.
string
업스트림 작업 ID(있는 경우).
string
시작 시각. 기간 필터와 청구 귀속의 기준이기도 합니다.
string
가장 최근 실행 시작 시각. 재시도할 때마다 다시 기록됩니다.
string
워커가 처음 실행을 가져온 시각. started_at과 달리 재시도에 덮어쓰지 않아 벽시계 기준: queued = first_started_at - created_at, 총 벽시간 = finished_at - first_started_at. started_at으로 queued를 구하면 이전 시도를 대기로 오산. 미할당만 null.
string
종료 시각.
object
객관 사용량: 실행이 한 일. 과금과 분리. 평가 비교 기준.
object
청구 원장 = 사용량 × 가격 × 청구 규칙. events[]는 청구 대상 이벤트를 수량, 단가, 금액과 함께 나열하고, total은 그 합계, charged는 청구가 적용되었는지 여부입니다. 최종 상태에 도달해야 확정됩니다.
object
실패 시 오류 객체(code / category / message / retryable).
object[]
응답 시점에 이미 최종 상태라면 첫 번째 배치의 레코드, 그렇지 않으면 null.
object[]
구조화된 경고(예: billing-qty-missing).

오류

오류 응답은 {"error": {code, category, message, retryable}}입니다. 오류 참고.

클라이언트 라이브러리

참고 사항

  • 상태 용어: PENDING, QUEUED, RUNNING, SUCCEEDED, PARTIALLY_SUCCEEDED, FAILED, CANCELLED, EXPIRED. 마지막 다섯 개가 최종 상태입니다.
  • 대기가 타임아웃되었다고 같은 목적의 두 번째 실행을 시작하지 마세요. 먼저 기존 run_id를 폴링하세요.
  • 실패한 실행에는 요금이 청구되지 않습니다. 부분 성공과 취소는 생성된 레코드에 대해서만 청구됩니다.