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 "https://www.socialcrawl.dev/v1/threads/profile?handle=zuck" \
-H "x-api-key: sc_your_key_here"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);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 "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 want | Call |
|---|---|
| Followers count, bio and bio link | GET /v1/threads/profile |
| A user's recent posts | GET /v1/threads/user/posts |
| One post in full, with its view count | GET /v1/threads/post |
| Replies on a post | GET /v1/threads/post/comments |
| Posts for a keyword, or for a name | GET /v1/threads/search |
| Accounts for a keyword | GET /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_countandjoined_atare 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_tagyourself. - Parent links between replies.
comment.parent_idis null on every reply, because the source never says which comment a nested reply answers.
Accounts and posts
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/threads/profile | 1 | Followers, bio, avatar, verification, profile URL, and the bio link | handle |
GET /v1/threads/user/posts | 1 to 165 | Roughly 15 recent posts, as one fixed window; include=engagement adds the view count and display name to each of them | handle, trim, include, limit (1-50) |
GET /v1/threads/post | 1 | One post's full detail object | url, 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
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/threads/post/comments | 1 to 10 | The reply window bundled with the post, typically about 20 replies | url, 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
limitabove 25, up to 50, to collect more replies in the same page. comment.post_idis the post you asked about.comment.parent_idis alwaysnull.
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"Search
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/threads/search | 1 to 26; 3 a post with coverage=full | Public 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 tag | query, limit (1-100), start_date, end_date, cursor, expand, coverage, include, label, relevance, judgments |
GET /v1/threads/search/users | 1 to 13 | Accounts matching a term, with display name, avatar and verification; include=profile adds the follower count, bio, private flag and bio link | query, include, limit (1-12) |
search returns one window of 15 to 20 posts. There are two ways to go deeper:
- Send
pagination.next_cursorback ascursorfor 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 alimit=100call 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 "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._warningsnames 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 -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
cursorbeside 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.
| Call | Token | What lands on each row | Cost |
|---|---|---|---|
search/users | include=profile | author.followers, author.bio, author.private, author.ext.bio_link | 1 per account filled, 12 at most |
user/posts | include=engagement | engagement.views, post.author.display_name, and the computed block that divides by views | 1 per post filled, 15 at most |
search | include=engagement | engagement.views, post.flags.pinned on the first 20 posts | 1 per post whose view count landed, 20 at most |
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, andlimitcaps rows and credits together. - It adds seconds. Measured on 11/09/2026: about 10 seconds for 15 posts.
data.hydrationreports how many rows were looked up, filled, cached and left unfilled.- On
searchit covers the first 20 posts, so it is refused withlimitabove 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.
Can I get the link in a Threads bio and the slides of a carousel?
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.
| Endpoint | Path | Credit Tier |
|---|---|---|
| Get Threads post details | /v1/threads/post | standard (1cr) |
| Get comments on a Threads post | /v1/threads/post/comments | standard (1-10cr)metered |
| Get Threads user profile | /v1/threads/profile | standard (1cr) |
| Search Threads posts | /v1/threads/search | standard (1-178cr)metered |
| Search Threads users | /v1/threads/search/users | standard (1-13cr)metered |
| List Threads user posts | /v1/threads/user/posts | standard (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
| Path | Rows per page | Date window | One call collects |
|---|---|---|---|
/v1/threads/post/comments | varies | since and until, applied to each page fetched | limit up to 50 |
/v1/threads/search | about 15 | since and until, applied to each page fetched | up to 5,000 rows or 50 pages; limit up to 100 |
/v1/threads/user/posts | varies | since and until, applied to each page fetched | limit 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.
| Path | Typical (median) | 95% finish within | Timeout to set |
|---|---|---|---|
/v1/threads/post | 3.3 s | 5.7 s | 16 s |
/v1/threads/post/comments | 3.3 s | 5.4 s | 14 s |
/v1/threads/profile | 3.5 s | 6.4 s | 15 s |
/v1/threads/search | 3.6 s | 9.2 s | 22 s |
/v1/threads/search/users | 2.0 s | 5.9 s | 12 s |
/v1/threads/user/posts | 5.6 s | 9.3 s | 44 s |
Platform notes
- A profile exists only if the account opted in. Many Instagram usernames have no Threads account, so a
404means no such profile. - Reshares split three ways.
engagement.sharesis the plain repost count.post.ext.quote_countcounts reposts with commentary, andpost.ext.reshare_countis the boosted figure shown in the app. post.flags.pinnedisnullon a plainsearchcall and filled on the first 20 rows withinclude=engagement.- Media URLs expire after a few hours, so re-fetch the post instead of storing them.
trim=truecosts the same and drops fields. It keeps only the id, text, shortcode, likes, timestamp and author, and everything else isnull.- Quote posts carry the quoted content at
post.ext.quoted_post.post.contentstays this post's own content. - Topic tags are at
post.ext.topic_tagon 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
Pagination
Cursor and page walks, and what has_more actually means.
Credits
What each tier costs and when a call is refunded.
API reference
Every parameter and response field, endpoint by endpoint.
The Meta network Threads accounts are attached to.
Bluesky
The other text network, same canonical Post object.
