스레드 검색 API, 한 호출에 55건

스레드 검색 API로 키워드를 치면 SocialCrawl GET /v1/threads/search가 한 창에 대략 15–20건을 1크레딧으로 돌려줘요. limit을 올리면 같은 호출에서 창을 이어 모아요. 2026-09-04 UTC 실측으로는 artificial intelligence에 limit=40을 넣었을 때 고유 게시물 55건·3크레딧이었어요.

이 글은 메타 공식 Threads API의 OAuth·게시 가이드가 아니에요. 월간 활성 사용자 5억인 Threads에서, 이미 쓰던 공개 읽기 경로가 같은 크레딧으로 더 많이 돌려주는 9월 개선을 가짜 JSON 없이 실제 호출로만 보여 드려요. 공식 키워드 검색 한도는 스레드 API 가이드에 따로 정리해 두었어요.

스레드 API 검색, 한 호출에 몇 건까지 모이나요?

기본 호출은 창 하나예요. 대략 15–20건에 1크레딧이 붙고, limit을 올리면 더 오래된 창을 이어서 걸어요.

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/threads/search?query=artificial%20intelligence"

같은 분(00:33 UTC)에 받은 응답 요약은 이래요.

{
  "success": true,
  "platform": "threads",
  "endpoint": "/v1/threads/search",
  "credits_used": 1,
  "cached": false,
  "pagination": {
    "has_more": true,
    "page_size": 19
  },
  "data": {
    "items": [
      {
        "post": {
          "id": "3978114690643853738",
          "url": "https://www.threads.com/@brandwithjoel/post/Dc1GjvzlwGq",
          "author": { "username": "brandwithjoel", "verified": true },
          "engagement": { "likes": 70, "comments": 34, "shares": 5 },
          "content": {
            "text": "If I need to explain why using AI for everything is a bad idea, we shouldn’t work together."
          }
        }
      }
    ]
  }
}

고유 게시물 19건, 크레딧 1, pagination.next_cursor 있음(값은 길어서 생략). 토픽 태그는 19건 중 6건에만 붙어 있었어요 (AI team, Author Threads 등). 위 JSON은 실제 봉투에서 항목을 하나만 남기고 줄인 거예요. stats 같은 필드는 응답에 없습니다.

같은 질의에 limit=40을 붙이면 창을 이어서 걸어요.

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/threads/search?query=artificial%20intelligence&limit=40"

호출	파라미터	고유 게시물	크레딧	next_cursor
한 창	query=artificial intelligence	19	1	있음
멀티 창	같은 질의 + limit=40	55	3	있음

겹치는 ID는 19개 중 14개, 새로 들어온 ID는 41개였어요. 창은 통째로 소비돼요. 마지막 창을 40에 맞춰 자르지 않아서 요청 40 → 실제 55가 나와요. SocialCrawl 쪽 limit 상한은 100이고, 이번 표본은 40까지만 넣었어요.

스레드 검색에서 긴 구절이 0건이면 어떻게 되나요?

정확한 구절만 찾고 싶을 때는 expand=false를 붙여요. the best coffee로 시험해 봤어요.

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/threads/search?query=the%20best%20coffee&expand=false"

결과는 0건·0크레딧. 빈 창은 청구하지 않아요.

같은 구절을 기본값(expand 생략, true)으로 다시 치면 건수가 달라져요.

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/threads/search?query=the%20best%20coffee"

호출	파라미터	고유 게시물	크레딧	커서	_warnings
정확 구절	expand=false	0	0	없음	없음
기본 expand	expand 생략	44	3	없음	하위질의 3개

응답 _warnings 원문은 이랬어요.

No Threads post matched "the best coffee" as a phrase, so the query was expanded into 3 narrower searches (best coffee, best, coffee) and 3 of them returned posts. Results are merged, de-duplicated and ordered by how many of your terms each post contains. You are billed 1 credit per search that returned posts, and an expanded response is a single page with no pagination cursor. Send expand=false to search the exact phrase only.

과금은 결과가 나온 하위질의당 1크레딧이에요. 정확 구절이 비면 0, 결과가 난 best coffee·best·coffee 세 개가 3크레딧. 확장 응답에는 페이지네이션 커서가 없어요. 한 창·limit 검색과 다른 점이에요.

(참고: 이전 측정에서는 다른 긴 구절이 0건→75건으로 바뀐 적이 있어요. 이번 글의 척추 숫자는 the best coffee 0→44예요.)

첫 히트는 @californiamaqui의 커피 게시물이었고, post.ext.topic_tag는 Coffee Threads였어요. 44건 중 토픽 태그가 있는 건 15건이었어요.

스레드 댓글 API로 답글은 어떻게 읽나요?

검색으로 게시물을 고른 뒤, 답글 창은 GET /v1/threads/post/comments로 읽어요. zuck 유저 게시물 창에서 답글이 가장 많았던 DZpPDXbCeTt(게시물 객체 기준 댓글 4,750)로 호출했어요.

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/threads/post/comments?url=https://www.threads.com/@zuck/post/DZpPDXbCeTt"

돌아온 건 댓글 22개·1크레딧, next_cursor=null, has_more=false예요. 부모 게시물의 전체 답글 수가 커도, 이 엔드포인트는 묶인 한 창만 줘요. 페이지네이션은 없어요.

{
  "success": true,
  "endpoint": "/v1/threads/post/comments",
  "credits_used": 1,
  "cached": false,
  "pagination": { "has_more": false, "page_size": 22 },
  "data": {
    "items": [
      {
        "comment": {
          "id": "3920732800241693703",
          "url": "https://www.threads.com/@din_kerinchi/post/DZpPbV5oPQH",
          "text": "As soon as the bots and ads are in, we are out. Deal?",
          "author": { "username": "din_kerinchi" },
          "engagement": { "likes": 2138, "replies": 33 },
          "post_id": null,
          "parent_id": null
        }
      }
    ]
  }
}

22개 모두 본문이 있었고, comment.url은 작성자 핸들+숏코드로 만든 퍼머링크예요. comment.post_id와 parent_id는 이번 표본에서 전부 null이었어요.

유저 게시물도 같은 한계예요. GET /v1/threads/user/posts?handle=zuck는 15건·1크레딧·커서 없음. 검색의 limit 워킹과는 달라요.

캐러셀·바이오 링크·토픽 태그는 응답 어디에 붙나요?

프로필부터 볼게요.

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/threads/profile?handle=zuck"

author.ext.bio_link **키는 오고, 값은 null**이었어요. 팔로워 5,724,910, verified, 바이오 "Mostly superintelligence and MMA takes". 웹사이트를 안 켠 계정이면 필드만 오고 URL은 비어요. 이번 수집에서는 null이 아닌 bio_link 예는 못 잡았어요.

유저 게시물 창(15건)에서는 캐러셀이 1개(DZ7eGA1G7wU, 슬라이드 3), /o1/v/t16/ 형태의 동영상 CDN URL이 1개(DcwLClnmOrR)였어요. 파일을 받아서 재생하진 않았고, 응답에 그 URL이 붙어 있다는 뜻이에요. 토픽 태그와 인용 게시물은 0/15.

게시물 상세로 캐러셀을 다시 읽으면 content.media_urls가 3개(jpg / webp / jpg)로 와요. computed.engagement_rate는 0.013216, 조회 411,634·좋아요 3,803. 미디어 CDN URL은 서명·만료가 있어서 쿼리스트링은 붙이지 않는 게 좋아요.

토픽 태그는 post.ext.topic_tag / topic_tag_id에 붙어요. 검색 한 창에서는 희소했고(6/19), zuck 유저 창에서는 0이었어요. quoted_post 필드도 스키마에 있지만, 이번 쇼케이스 표본(검색·유저 게시물·상세 합산)에서는 채워진 예가 없었어요. 예제 JSON은 만들지 않을게요.

어떻게 시작하나요?

1. SocialCrawl에 가입하고 API 키를 받아요. 무료 크레딧이 따라와요.
2. 스레드 검색 API 최소 호출은 아래예요. 키만 바꿔서 바로 재현할 수 있어요.

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/threads/search?query=the%20best%20coffee"

3. 그다음은 Threads 플랫폼 허브에서 엔드포인트 목록을 보고, 코드 한 줄 쓰기 전에 비주얼 익스플로러로 응답 모양을 먼저 확인해 보세요. 인증·봉투 규칙은 API 문서를 보세요.

이 글에 나온 숫자는 2026-09-04 00:33–00:37 UTC 실측이고, 쇼케이스 호출 합계는 12크레딧이었어요. 라이브 건수는 움직일 수 있지만 봉투 모양·크레딧 규칙·커서 동작은 그대로예요.

게시·OAuth·앱 심사가 궁금하면 공식 메타 스레드 API 정리와 Meta Get Started를 보세요. 공개 읽기·검색·댓글은 이 글과 Threads 허브 쪽이 맞아요.

자주 묻는 질문

스레드 검색 API 호출 한 번에 크레딧이 몇 개 드나요?

한 창은 1크레딧이에요. 실측 artificial intelligence는 19건·1크레딧. limit으로 창 N개를 이어 걸면 N크레딧이고, limit=40 실측은 3크레딧(55건)이었어요. 이번 런은 전부 cached=false라서 캐시 히트(0크레딧)는 없었어요.

limit은 최대 얼마까지 넣을 수 있나요?

제품 상한은 100이에요. 창은 통째로 소비되기 때문에 목표보다 많이 나올 수 있어요. 요청 40 → 실제 55가 그 예예요.

expand=false면 응답에서 무엇이 빠지나요?

정확한 구절만 검색해요. 실측 the best coffee는 0건·0크레딧. 기본 expand면 하위질의로 합쳐서 44건·3크레딧이 돌아왔고, 확장 응답에는 커서가 없어요.

스레드 댓글 API에 페이지네이션이 있나요?

없어요. 실측 22건에 next_cursor=null. 게시물 전체 답글 수가 커도 한 창만 받아요.

질의 분할이 일어나면 크레딧이 추가로 나가나요?

결과가 나온 하위질의당 1크레딧이에요. 정확 구절이 비면 0. 청구된 하위질의 목록은 _warnings에 적혀 있어요.

유저 게시물 엔드포인트도 검색처럼 100건까지 되나요?

아니요. 실측은 약 15건·1크레딧·커서 없음이에요. 검색의 limit 워킹과는 별개예요.

토픽 태그(topic_tag)는 응답 어디에 있나요?

post.ext.topic_tag와 topic_tag_id예요. 검색 창에서는 희소했고(6/19), zuck 유저 게시물 창에서는 0/15이었어요.