스레드

채널 코드 threads · 수집 환경 linux

Threads(스레드) 검색을 최신순/인기순으로, 필요하면 기간을 지정해 수집합니다. 인증 쿠키는 허브 '수집 인증'에서 중앙 관리하며, 수집할 때 워커가 받아 로그인 상태로 검색합니다(쿠키는 자동 갱신·만료 시 알림). 호출자는 키워드만 주면 되고, 시작일·종료일을 넣으면 그 범위의 글만 모읍니다(비우면 제한 없음 — 한쪽만 넣어도 됩니다). 검색 카드에 본문·작성자·반응수가 모두 있어 별도 상세 요청이 없습니다. 검색 결과에 나오는 답글도 구분 없이 수집하며 각 항목의 extra.is_reply로 원글과 구분할 수 있습니다. ⚠️ 로그인 채널이라 차단에 민감 — 호출 간격을 넉넉히. 무한 스크롤 방식이라 한 번에 최대 300건까지 수집합니다(그 이상은 긴 스크롤 세션이 체크포인트/레이트리밋 위험을 키워 안전 상한을 둠 — 더 필요하면 키워드/기간을 나눠 수집). 기간을 지정하면 Threads가 더 넓은 범위를 훑느라 '더보기' 응답이 느려질 수 있어 수집 시간이 늘어날 수 있습니다(수집기가 자동으로 더 기다립니다). 키워드 피드에 글이 적으면 그만큼만 수집됩니다.

요청 파라미터

아래 값들을 POST /api/v1/collect 의 params 객체에 담아 보냅니다.

키	타입	필수	기본	설명
keyword	text	예	—	Threads 검색어
limit	number	—	50	최대 수집 게시물 수 (상한 300 — 그 이상 요청해도 300으로 조정. 무한스크롤·차단 위험 때문)
filter	enum	—	recent	최신순(recent) 권장 — 기간을 지정할 때는 특히 recent를 쓰세요(인기순은 피드가 시간순이 아니라 기간 밖 글이 섞여 효율이 떨어집니다)
start_date	date (YYYY-MM-DD)	—	—	이 날짜 이후 글만 수집(당일 포함). 비우면 제한 없음. Threads 검색의 after_date로 전달되어 서버에서 걸러지고, 수집 후 작성일로 한 번 더 확인합니다
end_date	date (YYYY-MM-DD)	—	—	이 날짜까지 수집(당일 포함). 비우면 제한 없음. 시작일·종료일은 한쪽만 넣어도 됩니다(그쪽 방향으로만 제한)
exclude_keywords	text	—	—	이 단어가 본문에 들어간 글은 제외. 쉼표로 여러 개, 한 단어 안 띄어쓰기 허용

수집 기간(start_date ~ end_date)
검색은 최신순이라 위에서부터 훑어 내려갑니다.

둘 다 비우면 → 가장 최신 글부터 limit 개수까지 수집합니다.
start_date만 → 그 날짜 이후 글만 (그보다 오래된 글을 만나면 수집 종료).
end_date만 → 그 날짜까지(당일 포함). 그보다 최신 글은 건너뜁니다.
둘 다 → 두 날짜 사이 구간만 수집.

제외 키워드(exclude_keywords)
이 단어가 들어간 글은 수집 단계에서 걸러집니다. 쉼표(,)로 여러 개를 넣고, 한 단어 안에 띄어쓰기도 쓸 수 있습니다(예: "무료 나눔, 광고" → 무료 나눔·광고 두 개). 대소문자는 구분하지 않고 부분 일치로 판정합니다.

기본은 제목 기준 — 상세 요청을 보내기 전에 걸러서 빠르고, 수집 상한(limit)도 차감하지 않습니다.
비우면 → 제외 없이 전부 수집.

요청 예시

curl -X POST https://scraper.conbus.co.kr/api/v1/collect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "threads",
    "params": {
        "keyword": "로얄캐닌",
        "limit": 50,
        "filter": "recent",
        "start_date": "2026-06-01",
        "end_date": "2026-06-15",
        "exclude_keywords": "광고, 협찬"
    }
}'

응답 (202 Accepted)

요청은 즉시 큐에 적재되고 request_id 를 돌려줍니다. 실제 수집은 워커가 비동기로 처리합니다.

{ "success": true, "data": { "request_id": 42, "channel": "threads",
    "status": "pending", "status_url": "https://scraper.conbus.co.kr/api/v1/requests/42" } }

결과 조회 — `GET /requests/{id}`

같은 API 키로 request_id 를 조회합니다. 상태에 따라 응답이 달라집니다.

진행 중 (pending / running)

아직 끝나지 않았으면 progress 로 진행 상황만 옵니다(items 없음).

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "threads",
        "status": "running",
        "external_ref": null,
        "result_count": null,
        "started_at": "2026-06-16T09:00:05+09:00",
        "finished_at": null,
        "duration_ms": null,
        "duration_sec": null,
        "created_at": "2026-06-16T09:00:00+09:00",
        "updated_at": "2026-06-16T09:01:30+09:00",
        "progress": {
            "count": 12,
            "phase": "list"
        },
        "elapsed_ms": 85000
    }
}

완료 (done)

status 가 done 이면 data.items[] 에 결과가 담깁니다. 실패 시엔 status: "failed" 와 error 가 옵니다.

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "threads",
        "status": "done",
        "external_ref": null,
        "result_count": 1,
        "started_at": "2026-06-16T09:00:05+09:00",
        "finished_at": "2026-06-16T09:02:00+09:00",
        "duration_ms": 115000,
        "duration_sec": 115,
        "created_at": "2026-06-16T09:00:00+09:00",
        "updated_at": "2026-06-16T09:02:00+09:00",
        "items": [
            {
                "post_id": "someuser/3141592653589793",
                "url": "https://www.threads.net/@someuser/post/C8aBcDeFgHi",
                "title": "로얄캐닌 한 달 먹여본 솔직 후기 남깁니다 기호성은 확실히 좋은데 가격이 좀…",
                "author": "someuser",
                "posted_at": "2026-06-10T14:22:00+09:00",
                "views": null,
                "comment_count": 8,
                "recommends": 152,
                "body": "로얄캐닌 한 달 먹여본 솔직 후기 남깁니다 기호성은 확실히 좋은데 가격이 좀 부담스럽네요 그래도 재구매 의사는 있습니다",
                "source": "Threads",
                "extra": {
                    "author_name": "냥집사 데일리",
                    "like_count": 152,
                    "reply_count": 8,
                    "repost_count": 12,
                    "quote_count": 3,
                    "media": [
                        "https://scontent.cdninstagram.com/.../photo1.jpg"
                    ],
                    "source_kind": "search",
                    "is_reply": false
                }
            }
        ]
    }
}

실패 (failed)

status 가 failed 면 error 에 사유가 옵니다(items 없음). 일시적 실패는 자동 재시도되며, 위 응답은 마지막 시도 기준입니다.

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "threads",
        "status": "failed",
        "external_ref": null,
        "result_count": 0,
        "started_at": "2026-06-16T09:00:05+09:00",
        "finished_at": "2026-06-16T09:00:16+09:00",
        "duration_ms": 11000,
        "duration_sec": 11,
        "created_at": "2026-06-16T09:00:00+09:00",
        "updated_at": "2026-06-16T09:00:16+09:00",
        "error": "수집 실패 — 잠시 후 다시 시도하세요"
    }
}

최상위 data에는 항상 request_id·channel·status·external_ref·result_count·started_at·finished_at·duration_ms·duration_sec·created_at·updated_at이 포함되고, 상태에 따라 items(done)·progress+elapsed_ms(진행 중)·error(failed/cancelled)가 추가됩니다. duration_*는 허브가 잰 수집 소요 시간(시작~종료) — 자세히는 비동기 & 콜백. 요청을 잘못 시작했다면 취소 API로 중단할 수 있습니다.

결과 필드 (`items[]`)

필드	설명
post_id	글 고유 ID — `작성자핸들/게시물ID`. 재수집 중복 제거 키
url	Threads 퍼머링크 (`threads.net/@핸들/post/…`)
title / body	`title`은 본문을 80자로 자른 자동 생성값 / `body`는 게시물 본문 (`collect_body` 파라미터 없음)
author	작성자 핸들(`@아이디`)
posted_at	작성 시각 (ISO8601, KST)
views / comment_count	조회수는 수집하지 않아 `null` / `comment_count`=그 항목에 달린 답글 수
recommends	좋아요 수 (항상 채워짐)
source	`Threads` (고정)
extra.author_name	작성자 표시 이름
extra.like_count	좋아요 수
extra.reply_count	답글 수
extra.repost_count	리포스트 수
extra.quote_count	인용 수
extra.media	미디어 URL 배열
extra.source_kind	`search`
extra.is_reply	이 항목이 답글이면 `true`, 원글이면 `false`
extra.reply_to	답글이 향한 작성자 핸들(예: `sunny_hongmom`). 부모 원글이 검색 결과에 없어도 채워집니다 — 답글 항목에만 있고, 아니면 키 자체가 없습니다
extra.thread_parent	부모 원글의 `핸들/게시물ID` — 부모 원글이 같은 검색 결과에 함께 잡혔을 때만 채워집니다(아니면 키 없음)
extra.quote_of	인용 게시물일 때 — 인용한 원글의 `핸들/게시물ID`(아니면 키 없음)
extra.raw_text	수집 시점 카드 원문 스냅샷(감사·검증용)

채널 참고

로그인 세션이 필요합니다(허브 수집 인증). 조회수는 제공하지 않습니다(views=null).
정렬: filter로 최신순(recent)·인기순(top)을 고릅니다.
기간 지정(start_date / end_date) — 비우면 제한 없이 최신순으로 limit까지 모으고, 넣으면 그 범위의 글만 수집합니다. 한쪽만 넣어도 됩니다(그 방향으로만 제한). 두 날짜 모두 당일 포함이며, 작성일(KST) 기준입니다. 내부적으로는 Threads 검색의 after_date/before_date로 전달해 서버에서 1차로 걸러지고, 수집한 글의 작성일로 한 번 더 확인합니다 — 범위를 벗어난 글은 결과에서 빠지고 limit도 차감하지 않으며 그 수가 out_of_range로 집계됩니다.
기간을 쓸 때는 최신순(recent)을 권장합니다. 인기순(top)은 피드가 시간순이 아니라 기간 밖 글이 섞여 내려와, 같은 limit을 채우는 데 훨씬 오래 걸리고 out_of_range가 커집니다.
기간을 지정하면 Threads가 더 넓은 범위를 훑느라 스크롤 더보기 응답이 느려질 수 있습니다. 수집기는 새 글이 안 나올 때 대기 시간을 점점 늘려 기다리므로(적응형 대기) 조기 종료되지는 않지만, 전체 수집 시간이 길어질 수 있습니다. 긴 구간은 기간을 나눠 여러 번 호출하는 편이 안정적입니다(1회 최대 300건 상한과도 맞물립니다).
검색 결과에 나오는 항목을 구분 없이 그대로 수집합니다. Threads 검색은 원글뿐 아니라 키워드에 매칭된 답글도 함께 결과로 내보내므로 원글과 답글이 섞여 나옵니다. 답글도 제외하지 않고 담되, 아래 답글 관계 필드로 구분할 수 있습니다. (별도의 댓글/대댓글 상세 수집 기능은 제공하지 않습니다.)
답글 관계 필드 3종 — 용도가 다릅니다. extra.is_reply가 true면 답글입니다. 그 답글이 누구에게 달렸는지는 extra.reply_to(작성자 핸들), 어느 글에 달렸는지는 extra.thread_parent(핸들/게시물ID)로 알 수 있습니다. ⚠️ 둘의 커버리지가 다릅니다 — thread_parent는 부모 원글이 같은 검색 결과에 함께 잡혔을 때만 채워지므로, thread_parent만 보고 판단하면 답글의 상당수를 놓칩니다(부모가 결과에 없는 답글은 reply_to만 채워짐). 답글 여부는 is_reply, 상대는 reply_to를 기준으로 쓰고 thread_parent는 있을 때만 보조로 쓰는 것을 권장합니다. 인용 게시물은 extra.quote_of에 인용한 원글이 담깁니다.
무한 스크롤 방식이라 한 번에 최대 300건까지 수집합니다(그 이상 limit을 줘도 300으로 조정). 긴 스크롤 세션은 체크포인트/레이트리밋 위험을 키워 둔 안전 상한 — 더 필요하면 키워드/기간을 나눠 호출하세요.
키워드 검색 피드에 글이 적으면 그만큼만 수집됩니다(result_count가 limit보다 적어도 정상).

결과 수신(폴링·콜백) 방식은 비동기 & 콜백을 참고하세요.