계정 발견 시작

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

HTTP 요청

POST /ai/admin/tiktok-hashtag/start
Authorization: Bearer {access_token}
Content-Type: application/json

요청 본문

{
  "seedHashtags": ["뷰티", "스킨케어"],
  "mode": "EXPLORE",
  "targetCreators": 100,
  "maxHashtags": 100,
  "maxPagesPerTag": 8,
  "revisitAfterDays": 7
}

필드	범위·기본값	설명
`seedHashtags`	필수, 정규화 후 1~1,000개	앞의 `#`·양끝 공백 제거, 소문자화, 중복 제거. 빈 태그와 태그 내부 공백·쉼표는 거절
`mode`	`EXPLORE`(기본), `DAILY`	탐색 또는 지정 태그 수집
`targetCreators`	1~100,000	`EXPLORE` 필수. 기존 DB에 없는 신규 계정의 목표 수
`maxHashtags`	1~1,000, 기본 100	수집 해시태그 상한
`maxPagesPerTag`	1~30, 기본 8	태그당 페이지 상한
`revisitAfterDays`	0~365	최근 수집한 태그를 제외할 기간. `EXPLORE`에서 생략하면 Python 기본값 7. 0은 제외 기능을 끔

EXPLORE는 연관 해시태그로 탐색 범위를 넓힙니다. 해시태그·페이지 상한 등에 도달하면 목표보다 적게 끝날 수 있습니다.

DAILY는 입력한 태그만 한 번 수집하며, 이 요청으로 스케줄을 등록하지 않습니다. targetCreators는 생략하고 revisitAfterDays는 0 또는 생략해야 합니다.

{
  "seedHashtags": ["뷰티", "스킨케어"],
  "mode": "DAILY",
  "revisitAfterDays": 0
}

응답 (200 OK)

{
  "runId": "04f8e5cb-d3ea-4d72-88a8-e9ebdaac3a16",
  "executionName": "projects/.../executions/..."
}

응답 필드와 다음 단계

필드	타입	설명
`runId`	String (UUID)	상태 조회·상세 수집·중단에 사용할 실행 ID
`executionName`	String	Python이 시작한 Cloud Run 실행 이름

응답의 runId를 보관하고 상태 조회로 진행 상황을 확인합니다. 실행 목록 API는 제공하지 않습니다.

오류 응답

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

HTTP 상태	의미
`400`	필수값 누락, 허용 범위 초과, 잘못된 수집 모드 또는 JSON
`409`	이미 계정 발견 실행이 진행 중
`422`	Python 입력 검증 실패
`502`	수집 실행 또는 Python 응답 처리 실패
`503`	수집 Job 등 Python 실행 설정 오류
`504`	통신 시간 초과·응답 유실

{
  "detail": "이미 실행 중입니다: run_id=04f8e5cb-d3ea-4d72-88a8-e9ebdaac3a16 (RUNNING)."
}

409에 포함된 실행 ID로 기존 작업을 조회할 수 있습니다.

쓰기 요청은 자동 재시도하지 않습니다. 응답을 받지 못해도 요청이 반영됐을 수 있으므로 상태를 먼저 확인합니다.