SocialCrawl

Threads data API

Read profiles, posts and replies from Threads with one key and one response shape.

Read Meta's Threads data: profiles, a user's posts, one post's detail, the replies on a post, keyword search over public posts, and user search. Posts come back as the same canonical Post object you get from TikTok or Instagram, so one parser covers all three.

Threads search is a sampled window, and it varies from run to run. The same query run three times on 09/08/2026 returned 20 posts each time, but only 26 unique posts across the three runs (0.693 overlap). Every Threads provider behaves this way. A different set on a second run is not data loss.

Your first call

1. Fetch a profile

cURL
curl "https://www.socialcrawl.dev/v1/threads/profile?handle=zuck" \
  -H "x-api-key: sc_your_key_here"
TypeScript
const url = new URL("https://www.socialcrawl.dev/v1/threads/profile");
url.searchParams.set("handle", "zuck");
const res = await fetch(url, {
  headers: { "x-api-key": process.env.SOCIALCRAWL_API_KEY! },
});
const { data } = await res.json();
console.log(data.author.display_name, data.author.followers);
Python
import os
import requests

res = requests.get(
    "https://www.socialcrawl.dev/v1/threads/profile",
    headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]},
    params={"handle": "zuck"},
)
author = res.json()["data"]["author"]
print(author["display_name"], author["followers"])

The response is one author object: the handle, display name, bio, follower count, verification, the private flag and the Threads permalink. Measured on 22/11/2026: this call took about 5 seconds and cost 1 credit.

2. Fetch their content

cURL
curl "https://www.socialcrawl.dev/v1/threads/user/posts?handle=zuck" \
  -H "x-api-key: sc_your_key_here"

3. Read computed fields

When an endpoint supports a computed field and the required source inputs are present, the unified response includes that optional field. Depending on the endpoint, optional fields can include engagement_rate, language, content_category, and estimated_reach. See Computed fields for formulas, clamping rules, and null semantics. Where an endpoint supports them, list rows also carry judged labels (computed.labels, computed.relevance) by default at no extra credits; see Labels.

What it covers

What you wantCall
Followers count, bio and bio linkGET /v1/threads/profile
A user's recent postsGET /v1/threads/user/posts
One post in full, with its view countGET /v1/threads/post
Replies on a postGET /v1/threads/post/comments
Posts for a keyword, or for a nameGET /v1/threads/search
Accounts for a keywordGET /v1/threads/search/users

The full list, with credits per call, is under All endpoints.

What it does not cover

  • Following, post count, total likes and join date. Threads does not publish these four, so following, posts_count, likes_count and joined_at are always null.
  • Accounts that never opted in. A Threads profile exists only if the account created one, so many Instagram handles return a 404.
  • A reliable repeat of one search. Search is a sampled window, so a second run can return a slightly different set.
  • A tags-only search. Threads has no mode for every post under a topic tag, so group a keyword search by post.ext.topic_tag yourself.
  • Parent links between replies. comment.parent_id is null on every reply, because the source never says which comment a nested reply answers.

Accounts and posts

EndpointCreditsWhat it returnsKey parameters
GET /v1/threads/profile1Followers, bio, avatar, verification, profile URL, and the bio linkhandle
GET /v1/threads/user/posts1 to 165Roughly 15 recent posts, as one fixed window; include=engagement adds the view count and display name to each of themhandle, trim, include, limit (1-50)
GET /v1/threads/post1One post's full detail objecturl, trim

Pass handles without the @. The bio website is author.ext.bio_link, or null when none is set.

user/posts has no cursor. With limit off or 15 or less, you get about 15 posts for 1 credit. A larger limit collects up to 50 posts of the same feed at 3 credits per post, with views already filled. For older posts, run search with the handle and a date window, or use /v1/search/everywhere.

Replies

EndpointCreditsWhat it returnsKey parameters
GET /v1/threads/post/comments1 to 10The reply window bundled with the post, typically about 20 repliesurl, trim, limit (1-50)

Each reply carries text, likes, reply count, author, avatar, verification, pinned flag and timestamp. A post and its replies come from one request, so calling both saves nothing.

  • There is one window and no cursor. Send limit above 25, up to 50, to collect more replies in the same page.
  • comment.post_id is the post you asked about. comment.parent_id is always null.
cURL
curl "https://www.socialcrawl.dev/v1/threads/post/comments?url=https://www.threads.com/@zuck/post/DZpPDXbCeTt" \
  -H "x-api-key: sc_your_key_here"
EndpointCreditsWhat it returnsKey parameters
GET /v1/threads/search1 to 26; 3 a post with coverage=fullPublic posts matching a keyword; include=engagement adds the view count and pinned flag to the first 20; coverage=full searches Threads' Top tab for names and phrases with no topic tagquery, limit (1-100), start_date, end_date, cursor, expand, coverage, include, label, relevance, judgments
GET /v1/threads/search/users1 to 13Accounts matching a term, with display name, avatar and verification; include=profile adds the follower count, bio, private flag and bio linkquery, include, limit (1-12)

search returns one window of 15 to 20 posts. There are two ways to go deeper:

  • Send pagination.next_cursor back as cursor for the next, older window at 1 credit.
  • Set limit. The API walks shrinking date windows and returns at least that many unique posts. It bills 1 credit per window used and refunds the rest, so a limit=100 call that runs dry after three windows costs 3 credits.

The limit is a target, not a page size, so limit=40 typically returns 50 to 60 posts. A value outside 1 to 100 is a free 400.

start_date and end_date are inclusive YYYY-MM-DD dates. The walk never crosses start_date, so the pair pages a fixed period at a known cost. A bad date is a free 400. For a stable set, collect over a bounded window and remove duplicates by post id.

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

curl "https://www.socialcrawl.dev/v1/threads/search?query=artificial%20intelligence&limit=60&start_date=2026-07-01&end_date=2026-07-31" \
  -H "x-api-key: sc_your_key_here"

Long queries are handled for you

Threads matches a query against topic tags it knows, so an unknown phrase returns nothing. When a query comes back empty, the API splits it into word pairs, searches them in parallel and returns one merged list. Measured on 31/08/2026, best coffee machine for a small office went from 0 posts to 75.

  • You pay 1 credit for each relaxed search that returned posts, at most 4 on top of the original. A query that already worked costs 1 credit.
  • A relaxed response is one page with no cursor.
  • data._warnings names every search that ran.

Send expand=false to search the exact phrase only. If your balance covers that call but not the relaxed one, it runs with expand=false instead of answering 402. See Errors.

Names and phrases with no topic tag

Relaxation cannot find a person whose name is no topic tag. Send coverage=full and the query runs against the Top tab on threads.com. Measured on 19/11/2026, a trending person went from 0 posts to 20.

cURL
curl -G "https://www.socialcrawl.dev/v1/threads/search" \
  -H "x-api-key: sc_your_key_here" \
  --data-urlencode "query=artificial intelligence" \
  --data-urlencode "coverage=full"
  • It costs 3 credits per post, 20 posts by default and 50 at most. A page with no post about the query is free.
  • It is one page, and a cursor beside it is a free 400.
  • Posts come in Top order, so identical calls can differ.
  • A call usually takes 10 to 25 seconds.

Filling the numbers a list leaves out

Account search carries no follower count or bio, and neither post list carries a view count. Add include and the API fetches them inside the same call.

CallTokenWhat lands on each rowCost
search/usersinclude=profileauthor.followers, author.bio, author.private, author.ext.bio_link1 per account filled, 12 at most
user/postsinclude=engagementengagement.views, post.author.display_name, and the computed block that divides by views1 per post filled, 15 at most
searchinclude=engagementengagement.views, post.flags.pinned on the first 20 posts1 per post whose view count landed, 20 at most
cURL
curl "https://www.socialcrawl.dev/v1/threads/search/users?query=tech&include=profile" \
  -H "x-api-key: sc_your_key_here"
  • You pay only for rows that come back filled. An unfilled row is refunded and named in data._warnings, and limit caps rows and credits together.
  • It adds seconds. Measured on 11/09/2026: about 10 seconds for 15 posts.
  • data.hydration reports how many rows were looked up, filled, cached and left unfilled.
  • On search it covers the first 20 posts, so it is refused with limit above 20.
  • A brand-new post has no view count yet, and that costs nothing.

Questions people ask

How do I get more than 20 posts from one Threads search, and what is the maximum limit?

GET /v1/threads/search returns one window of about 15 to 20 posts. There are two ways to go deeper. Send pagination.next_cursor back as cursor for the next, older window. Or set limit between 1 and 100, and the API walks windows until it holds that many unique posts. The limit is a collection target, not a page size, so limit=40 typically returns 50 to 60 posts. A limit outside 1 to 100 is a free 400. start_date and end_date bound the walk.

Why does a Threads search time out at 10 seconds?

The windows of a limit walk run one after another, at roughly 3.4 seconds each, so a high limit is a long request. Measured on 07/09/2026 with a cold cache: a call with no limit took 3.5 seconds for 20 posts, limit=50 took 10.2 seconds and limit=100 took 19.5 seconds. A client with a 10-second default timeout cannot fit limit=50 or more. Raise the timeout well above 20 seconds for a large limit, or ask for a smaller limit and page with pagination.next_cursor, which costs the same credits for the same posts.

Is Threads search limited to two words?

No. Threads matches a query against topic tags it already knows, so a phrase it does not recognize can return nothing whatever its length: machine learning engineer returns a full window and the best coffee returns none. When a query comes back empty, the API splits it into adjacent word pairs, runs those searches in parallel and returns one merged list. It bills 1 credit for each relaxed search that returned posts. Send expand=false to search the exact phrase only. For a person's name with no topic tag, send coverage=full.

Yes to both. The website a user sets in their bio is author.ext.bio_link on GET /v1/threads/profile, and it is null when none is set. A carousel post returns every slide as an array in post.content.media_urls. A video post returns a playable URL there, with the cover frame in post.content.thumbnail_url. A quote post carries the quoted content at post.ext.quoted_post.

All endpoints

6 endpoints available.

EndpointPathCredit Tier
Get Threads post details/v1/threads/poststandard (1cr)
Get comments on a Threads post/v1/threads/post/commentsstandard (1-10cr)metered
Get Threads user profile/v1/threads/profilestandard (1cr)
Search Threads posts/v1/threads/searchstandard (1-178cr)metered
Search Threads users/v1/threads/search/usersstandard (1-13cr)metered
List Threads user posts/v1/threads/user/postsstandard (1-165cr)metered

How far back and how deep

Each list returns one page at a time. Send cursor for the next page, or max_items or max_pages to collect several pages in one call. A page size appears only where it has been verified. How paging works

PathRows per pageDate windowOne call collects
/v1/threads/post/commentsvariessince and until, applied to each page fetchedlimit up to 50
/v1/threads/searchabout 15since and until, applied to each page fetchedup to 5,000 rows or 50 pages; limit up to 100
/v1/threads/user/postsvariessince and until, applied to each page fetchedlimit up to 50

How long a call takes

Measured on production calls that were not served from the cache, 14/10/2026 to 21/10/2026. A cached call answers faster. Set your client timeout to the value in Timeout to set, so a slow call is not cut off and sent again.

PathTypical (median)95% finish withinTimeout to set
/v1/threads/post3.3 s5.7 s16 s
/v1/threads/post/comments3.3 s5.4 s14 s
/v1/threads/profile3.5 s6.4 s15 s
/v1/threads/search3.6 s9.2 s22 s
/v1/threads/search/users2.0 s5.9 s12 s
/v1/threads/user/posts5.6 s9.3 s44 s

Platform notes

  • A profile exists only if the account opted in. Many Instagram usernames have no Threads account, so a 404 means no such profile.
  • Reshares split three ways. engagement.shares is the plain repost count. post.ext.quote_count counts reposts with commentary, and post.ext.reshare_count is the boosted figure shown in the app.
  • post.flags.pinned is null on a plain search call and filled on the first 20 rows with include=engagement.
  • Media URLs expire after a few hours, so re-fetch the post instead of storing them.
  • trim=true costs the same and drops fields. It keeps only the id, text, shortcode, likes, timestamp and author, and everything else is null.
  • Quote posts carry the quoted content at post.ext.quoted_post. post.content stays this post's own content.
  • Topic tags are at post.ext.topic_tag on tagged posts only. There is no tags-only search, so group a keyword search by that field yourself.

Labels

Threads lists label their rows by default, at no extra credit. On /v1/threads/search, each row carries sponsored, intent and niche, plus a computed.relevance score for your query. Add relevance=filter to drop off-topic rows, or send judgments=off to remove all of it. See Labels.

Next steps