상태 조회

모든 요청에 ADMIN 권한의 액세스 토큰이 필요합니다. 성공 응답은 Python의 JSON 객체를 그대로 반환하며 ApiResponse.data로 감싸지 않습니다.

HTTP 요청

GET /ai/admin/tiktok-hashtag/status/{runId}?minFollowers=1000
Authorization: Bearer {access_token}

경로 파라미터

이름	타입	필수	설명
`runId`	String (UUID)	예	계정 발견 시작의 응답에서 받은 실행 ID

쿼리 파라미터

이름	타입	필수	범위·기본값
`minFollowers`	Integer	아니오	0~10,000,000, 기본 1,000

enrichTargets는 이 하한 이상이면서 아직 상세 수집하지 않은 계정 수입니다. 상세 수집 실행에 사용할 팔로워 하한과 동일한 값으로 조회해야 화면의 대상 수가 일치합니다.

응답 (200 OK)

{
  "runId": "04f8e5cb-d3ea-4d72-88a8-e9ebdaac3a16",
  "status": "RUNNING",
  "seedHashtags": ["뷰티", "스킨케어"],
  "targetCreators": 100,
  "discoveredCreators": 82,
  "newCreators": 64,
  "visitedHashtags": 8,
  "skippedHashtags": 2,
  "frontierSize": 16,
  "consecutiveDryTags": 0,
  "apiCalls": 24,
  "storedVideos": 110,
  "enrichStatus": null,
  "enrichedCreators": 0,
  "enrichTargets": 20,
  "enrichTargetsMinFollowers": 1000,
  "executionName": "projects/.../executions/...",
  "errorMessage": null,
  "createdAt": "2026-09-10T06:30:00Z",
  "completedAt": null
}

발견 상태 status: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED.
상세 수집 상태 enrichStatus: 시작 전 null, 이후 PENDING, RUNNING, COMPLETED, FAILED.
discoveredCreators는 전체 발견 계정, newCreators는 신규 계정 수입니다.
visitedHashtags는 개수이며 태그 목록이 아닙니다.
두 작업 상태 중 하나라도 진행 중이면 조회를 계속해야 합니다. 프론트 연동 시 5초 간격 조회를 권장합니다.
조회 요청이 실패해도 수집 자체가 실패한 것은 아닙니다. 조회 오류와 작업의 FAILED 상태를 구분합니다.

응답 필드

필드	타입	설명
`runId`	String	실행 UUID
`status`	String	계정 발견 상태
`seedHashtags`	String[]	정규화된 시작 해시태그
`targetCreators`	Integer	탐색 모드의 신규 계정 목표. 지정 태그 모드는 0
`discoveredCreators`	Integer	발견한 전체 계정 수
`newCreators`	Integer	신규 계정 수
`visitedHashtags`	Integer	수집한 태그 수
`skippedHashtags`	Integer	건너뛴 태그 수
`frontierSize`	Integer	대기 중인 태그 수
`consecutiveDryTags`	Integer	신규 계정 없이 연속 처리한 태그 수
`apiCalls`	Integer	수집 API 호출 수
`storedVideos`	Integer	저장 영상 수
`enrichStatus`	String 또는 null	상세 수집 상태. 시작 전에는 null
`enrichedCreators`	Integer	상세 수집 완료 계정 수
`enrichTargets`	Integer	조회한 팔로워 하한을 충족하는 미수집 대상 수
`enrichTargetsMinFollowers`	Integer	대상 집계에 사용한 팔로워 하한
`executionName`	String 또는 null	계정 발견의 Cloud Run 실행 이름
`errorMessage`	String 또는 null	실패 사유
`createdAt`	String	실행 생성 시각 (ISO 8601)
`completedAt`	String 또는 null	계정 발견 종료 시각 (ISO 8601)

조건을 충족한 계정은 상세 지표 수집으로 추가 수집합니다. 현재 API는 실행별 계정 목록·CSV 다운로드를 제공하지 않습니다.

오류 응답

아래 상태는 실제 HTTP 상태 코드입니다. 오류 본문은 {"detail":"..."} 형식이며, Python 입력 검증 오류의 detail은 배열일 수 있습니다. 로그인·권한 오류는 기존 공통 관리자 인증 응답을 따릅니다.

HTTP 상태	의미
`400`	잘못된 UUID 또는 팔로워 하한
`404`	실행 없음
`422`	Python 입력 검증 실패
`502`	Python 요청·응답 처리 실패
`504`	통신 시간 초과·응답 유실