Threads API

Endpoints

Quick start

Coverage & limits

• Independent worker on port 3040, THREADS_API_KEY in x-api-key. No Threads or Instagram account, login, storage, media download or product dependency; each operation runs one anonymous session with a browser TLS fingerprint, the way Threads' own web client connects.
• Four concurrent operations, 45-second deadline, at most five upstream requests per operation: profile, posts, replies, post and comments = one page load (plus one canonical redirect hop for short, threads.net or re-attributed permalinks, and one re-read on a fresh session when a page arrives without its data); a post without comments, search and topic search = the session probe (a HEAD on the login route, plus the login page when the probe sets no cookie) plus one document; user search = thirteen: the web index and its fallback, up to ten profile pages (five by default) and the retry; each with one shared transient retry for network failures or HTTP 5xx. Challenges, rate limits and 4xx answers are never retried. A page read stops once the data the operation needs has arrived.
• 8 MiB decoded response across an operation (16 MiB for user search, which reads up to ten profile pages), 600,000 JSON nodes, 64 levels, 50 posts and 50 continuation posts per profile window, 50 replies, 50 comments, 20 related posts, 50 parent posts, 50 search results, 20 topic tags, 10 users.
• Windows: the profile feed (posts_first_page_only), the replies tab (replies_first_page_only), the reply window of a post (comments_first_page_only) and the search window (about twenty posts) are each returned as one page. Private accounts answer the profile header and an empty posts or replies window with private_account.
• Keyword user search uses SERPER_API_KEY (Serper Google Search API) and falls back to THREADS_SEARCH_API_KEY or BRAVE_SEARCH_KEY (Brave Search API) when Serper is unset or fails; the route reports search_unavailable without either. One index request per search, plus one fallback request (10 URLs requested from Serper, 20 from Brave; profile permalinks kept, at most 10), 1 MiB index response, then one profile page per account (five by default, up to ten with limit; three at a time; pages that no longer resolve are omitted as users_omitted); results are ordered by the index.
• The search, post and topic document ids are pinned to the ones Threads' web client uses; when Threads retires one, the operation fails operation_unavailable instead of guessing.
• Handles are 1–30 letters, digits, periods and underscores (leading @ accepted), post URLs are threads.com or threads.net /@handle/post/<code>, /t/<code> or /post/<code> permalinks (query strings and fragments ignored). Identity is verified against the request; mismatches fail unsupported_page. Unknown handles and unknown post codes fail not_found.
• Optional THREADS_PROXY_URL (falling back to TWITCH_PROXY_URL, then REDDIT_PROXY_URL) routes every operation through a fresh residential proxy session; an optional second pool (THREADS_PROXY_FALLBACK_URL) takes over from stalled tunnels and serves the fresh-session re-read.