스레드

채널 코드 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로 전달되어 서버에서 걸러지고, 수집 후 작성일로 한 번 더 확인합니다. ⚠️ 기간을 넣으면 Threads 매칭이 느슨해져(단어 OR·부분 일치) 무관한 글이 섞입니다 — 키워드 검증(기본 all)이 걸러내며, 영문+한글 결합 키워드는 Threads 검색어를 따로 두세요
end_date	date (YYYY-MM-DD)	—	—	이 날짜까지 수집(당일 포함). 비우면 제한 없음. 시작일·종료일은 한쪽만 넣어도 됩니다(그쪽 방향으로만 제한)
exclude_keywords	text	—	—	이 단어가 본문에 들어간 글은 제외. 쉼표로 여러 개, 한 단어 안 띄어쓰기 허용
keyword_match	enum	—	all	수집한 글의 본문에 키워드가 있는지 워커가 확인해 없으면 버립니다(수집 상한 미차감, 요약 keyword_missing 집계). all=키워드를 단어로 나눠 전부 있어야 통과(순서 무관, 기본) · exact=입력 문자열 그대로(공백만 무시) · any=단어 하나라도(노이즈를 못 막음 — 호환용) · off=검증 없이 Threads 결과 전부 저장(종전 동작). 대소문자·공백 무시, URL·@핸들 제외, 3자 이하 영문(lg·sk·kt)은 단어 경계 필수
search_term	text	—	—	Threads에 실제로 보낼 검색어. 비우면 키워드 그대로. 기간 검색은 매칭이 느슨해 "LG유플러스"가 "lg" 검색이 되므로, 이럴 땐 "유플러스"처럼 변별력 있는 한 단어를 넣고 키워드 검증으로 원래 키워드를 확인하게 하세요. 기간 검색이면서 키워드가 "짧은 영문+한글"(LG유플러스·SK텔레콤)이면 비워도 자동으로 한글 부분만 보냅니다(요약 server_query에 실제 검색어 기록)
keyword_aliases	text	—	—	이 표기가 본문에 있으면 키워드가 없어도 통과. 쉼표로 여러 개(예: LG U+, 엘지유플러스, 유플). 변형 표기 구제용
keep_thread_context	bool	—	false	켜면 검증을 통과한 글의 작성자에게 달린 답글은 키워드가 없어도 함께 저장합니다(extra.keyword_context=true, 상한 안에서). 브랜드 언급 글의 대화 흐름까지 볼 때. 기본 꺼짐
require_korean	bool	—	true	본문에 한글이 없는 글은 버립니다(수집 상한 미차감, 요약 lang_missing 집계). KT처럼 영문 키워드는 검증을 통과해도 말레이·인니어의 kt 같은 글이 30~45% 남아 기본 켜 둡니다. 한글 키워드는 검증 통과 시 본문에 한글이 있어 영향 없음. 영문 글도 받아야 하면 끄세요

수집 기간(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": "광고, 협찬",
        "keyword_match": "all",
        "keep_thread_context": false,
        "require_korean": true
    }
}'

응답 (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 를 조회합니다. 상태에 따라 응답이 달라집니다. 결과(items)는 요청별로 보관되므로 같은 글이 다른 요청(다른 키워드·재수집)에 겹쳐도 이 요청의 결과는 그대로입니다 — 여러 요청에 걸친 중복 정리는 post_id로 호출 쪽에서 하세요. 보존 기간은 완료 후 90일입니다. 보존 기간이 지나면 items 는 빈 배열이고 items_expired: true, items_keep_days 가 함께 옵니다(status 는 그대로 done).

진행 중 (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	수집 시점 카드 원문 스냅샷(감사·검증용)
extra.keyword_hit	키워드 검증 통과 여부(`true`/`false`) — `keyword_match=off`면 `false`인 항목도 저장됩니다
extra.keyword_context	`keep_thread_context`로 키워드 없이 맥락으로 살린 답글이면 `true`(아니면 키 없음)

채널 참고

로그인 세션이 필요합니다(허브 수집 인증). 조회수는 제공하지 않습니다(views=null).
정렬: filter로 최신순(recent)·인기순(top)을 고릅니다.
기간 지정(start_date / end_date) — 비우면 제한 없이 최신순으로 limit까지 모으고, 넣으면 그 범위의 글만 수집합니다. 한쪽만 넣어도 됩니다(그 방향으로만 제한). 두 날짜 모두 당일 포함이며, 작성일(KST) 기준입니다. 내부적으로는 Threads 검색의 after_date/before_date로 전달해 서버에서 1차로 걸러지고, 수집한 글의 작성일로 한 번 더 확인합니다 — 범위를 벗어난 글은 결과에서 빠지고 limit도 차감하지 않으며 그 수가 out_of_range로 집계됩니다.
⚠️ 기간을 넣으면 Threads 검색의 매칭이 느슨해집니다. 키워드를 단어로 쪼개 OR로 잇고 URL·핸들까지 부분 일치로 보기 때문에, LG유플러스는 사실상 lg 검색이 되어 무관한 외국어 글이 섞입니다(2026-09 실측: 198건 중 유플러스 0건). 그래서 키워드 검증(keyword_match, 기본 all)이 저장 전에 본문을 확인해 걸러내고, 영문+한글이 붙은 키워드는 기간 검색에서 한글 부분만 자동으로 검색어로 보냅니다(LG유플러스→유플러스, 요약 server_query에 기록). 다어절 키워드는 search_term에 변별력 있는 한 단어를 직접 지정하세요.
키워드 검증(keyword_match) — 수집한 글의 본문(+카드 원문)에 요청 키워드가 있는지 워커가 확인해 없으면 버립니다(limit 미차감, 요약 keyword_missing·keyword_hit_rate 집계, 각 항목 extra.keyword_hit). all=단어 전부(순서 무관, 기본) · exact=입력 그대로(공백만 무시) · any=단어 하나라도(노이즈를 못 막음, 호환용) · off=검증 없이 전부 저장(종전 동작). 비교는 대소문자·공백 무시, URL·@핸들 제외, 3자 이하 영문(lg·sk·kt)은 단어 경계 필수(tiktok·lg.jp는 불일치). 변형 표기는 keyword_aliases(쉼표 구분, 예 LG U+, 엘지유플러스)로 인정할 수 있고, 통과 글 작성자에게 달린 답글까지 남기려면 keep_thread_context=true(extra.keyword_context). 통과율이 30% 미만(판정 20건 이상)이면 허브가 그 잡을 점검 대상(flagged)으로 표시합니다.
한국어 글만(require_korean, 기본 true) — 본문에 한글이 없는 글은 버립니다(limit 미차감, 요약 lang_missing). KT처럼 영문 키워드는 검증을 통과해도 말레이·인니어의 kt(=kat) 같은 글이 30~45% 남아 기본으로 켜 둡니다. 한글 키워드는 검증 통과 시 본문에 한글이 있으므로 영향이 없고, 영문 글도 받아야 하면 false로 끄세요.
기간을 쓸 때는 최신순(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보다 적어도 정상).

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