Threads APIthreads.com ↗
Search Threads posts and user profiles by keyword. Returns text, engagement metrics (likes, replies, reposts), media URLs, and verification status.
What is the Threads API?
The Threads API exposes 2 endpoints for searching posts and user accounts on threads.com. The search_posts endpoint returns matching thread content alongside like counts, reply counts, repost counts, quote counts, media presence, and link preview data. The search_users endpoint returns profile records including username, display name, profile picture URL, and verification status — covering the core discovery surface of the platform.
curl -X GET 'https://api.parse.bot/scraper/385c1faa-d444-4758-bf57-373b43a7cbe4/search_posts?limit=5&query=artificial+intelligence&search_surface=default' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace threads-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Threads Search API — find posts and users by keyword."""
from parse_apis.threads_search_api import Threads, SearchSurface, QueryRequired
client = Threads()
# Search for recent posts about a topic, capped at 5 results.
for post in client.posts.search(query="artificial intelligence", search_surface=SearchSurface.RECENT, limit=5):
print(post.text[:80], "| likes:", post.like_count, "| replies:", post.reply_count)
# Drill into the first post's author info.
post = client.posts.search(query="python programming", limit=1).first()
if post:
print(post.user.username, post.user.full_name, "verified:", post.user.is_verified)
print("images:", len(post.images), "has_video:", post.has_video)
# Search for user accounts and inspect profiles.
for user in client.users.search(query="tech", limit=3):
print(user.username, user.full_name, "active:", user.is_active_on_threads)
# Typed error handling: catch a missing-query error.
try:
client.posts.search(query="", limit=1).first()
except QueryRequired as exc:
print(f"Query required: {exc}")
print("exercised: posts.search / users.search / QueryRequired error handling")
Full-text search over Threads posts by keyword. Returns matching posts with text content, engagement metrics (likes, replies, reposts, quotes), author info, media URLs, and link previews. Results are server-ranked; search_surface controls recency bias. Each post includes an embedded author object. No cursor-based pagination — a single page of up to `limit` results is returned per call.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of posts to return |
| queryrequired | string | Search keyword or phrase |
| search_surface | string | Search surface type that controls result ranking. |
{
"type": "object",
"fields": {
"posts": "array of post objects with id, code, text, created_at, like_count, reply_count, repost_count, quote_count, is_reply, has_video, media_type, images, link_preview, and user",
"query": "string, the search query used",
"total_results": "integer, number of posts returned"
},
"sample": {
"data": {
"posts": [
{
"id": "3911074115188480204",
"code": "DZG7S-eCNjM",
"text": "As the global race for artificial intelligence accelerates...",
"user": {
"id": "63434265578",
"username": "nazakat_ali_khowaja",
"full_name": "Nazakat Ali Khowaja",
"is_verified": false,
"profile_pic_url": "https://scontent.cdninstagram.com/profile.jpg"
},
"images": [
"https://scontent.cdninstagram.com/example.jpg"
],
"is_reply": false,
"has_video": false,
"created_at": 1780456388,
"like_count": 4042,
"media_type": 1,
"quote_count": 9,
"reply_count": 148,
"link_preview": null,
"repost_count": 73
}
],
"query": "artificial intelligence",
"total_results": 3
},
"status": "success"
}
}About the Threads API
Endpoints Overview
The API provides two GET endpoints: search_posts and search_users. Both accept a required query string and an optional limit integer to control result volume. search_posts additionally accepts a search_surface parameter with values default or recent, allowing you to target either relevance-ranked results or chronologically recent posts.
Post Search Response Shape
search_posts returns an array of post objects under the posts key. Each object includes the post id, a short code identifier, the full text of the thread, a created_at timestamp, and four engagement counters: like_count, reply_count, repost_count, and quote_count. Boolean fields is_reply and has_video indicate post type and media presence. The response also carries the original query string and a total_results count for the returned set.
User Search Response Shape
search_users returns an array under users. Each user object includes id, username, full_name, profile_pic_url, is_verified (boolean for the blue-check badge), and is_active_on_threads (boolean indicating whether the account is actively posting on Threads). The query and total_results fields appear at the response root, matching the structure of the post endpoint.
Practical Notes
Neither endpoint exposes follower counts, following lists, or individual post comment threads — only the top-level engagement counters. Pagination beyond the limit parameter is not available; you get a single batch per request. The search_surface option on search_posts is the primary lever for shifting between trending/relevant and time-ordered results.
The Threads API is a managed, monitored endpoint for threads.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when threads.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official threads.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track how often a brand or product name appears in Threads posts and monitor like/repost counts over time.
- Identify verified Threads accounts in a given topic area using
is_verifiedfromsearch_users. - Aggregate quote counts and repost counts for a keyword to measure discussion spread without full social listening tooling.
- Build a lightweight creator discovery tool by combining
search_usersresults withis_active_on_threadsfiltering. - Detect posts containing video by filtering on
has_videoto surface multimedia content for a given keyword. - Compare engagement metrics (likes, replies, reposts, quotes) across posts matching a search term to rank discussion intensity.
- Separate original posts from reply threads in search results using the
is_replyboolean field.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Threads have an official developer API?+
What does `search_surface` actually change in `search_posts` results?+
search_surface to recent returns posts ordered by recency rather than relevance. The default value returns results ranked by Threads' relevance scoring. Both surfaces return the same response fields; only the ordering and selection of posts differs.Does the API return follower or following counts for users?+
search_users returns id, username, full_name, profile_pic_url, is_verified, and is_active_on_threads. Follower and following counts are not included. You can fork this API on Parse and revise it to add a profile detail endpoint that exposes those fields.Can I retrieve individual post replies or comment threads?+
reply_count integer on each post but does not return the actual reply objects. Only top-level threads appear in search results, with is_reply flagging which results are themselves replies to other posts. You can fork this API on Parse and revise it to add a replies endpoint for a given post ID.Is there a way to paginate through more results than the `limit` parameter allows?+
limit you provide, with no cursor or offset parameter for additional pages. You can fork this API on Parse and revise it to add cursor-based pagination if you need deeper result sets.