{"openapi":"3.0.3","info":{"title":"Threads API (ReefAPI)","version":"0.4.0","description":"Threads API scraper — public Threads (Meta) profiles, posts, replies, reposts, post detail, conversations and search (no login, public content only) Call POST /threads/v1/{action} with an x-api-key header; every response is the { ok, data, meta, error } envelope.","contact":{"name":"ReefAPI","url":"https://reefapi.com/threads-api","email":"support@reefapi.com"},"license":{"name":"ReefAPI Terms","url":"https://reefapi.com/terms"},"termsOfService":"https://reefapi.com/terms"},"externalDocs":{"description":"Threads API documentation","url":"https://reefapi.com/docs/threads"},"servers":[{"url":"https://api.reefapi.com"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"threads","description":"Threads API scraper — public Threads (Meta) profiles, posts, replies, reposts, post detail, conversations and search (no login, public content only)"}],"paths":{"/threads/v1/profile":{"post":{"operationId":"threads_profile","summary":"Public Threads profile by username — name, bio, bio links, follower count, verification, profile picture and user id.","description":"Public Threads profile by username — name, bio, bio links, follower count, verification, profile picture and user id.","tags":["threads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","example":"zuck","description":"Threads handle without the @ (the name in threads.com/@<username>)."}},"required":["username"]},"example":{"username":"zuck"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/threads/v1/posts":{"post":{"operationId":"threads_posts","summary":"Public posts from a Threads profile (most-recent first)","description":"Public posts from a Threads profile (most-recent first). Returns full text, media, engagement counts, location and music per post. Set `limit` for how many to return.","tags":["threads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","example":"zuck","description":"Threads handle without the @ (the name in threads.com/@<username>)."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25,"description":"Max items to return (1-100). Larger values are clamped to 100."}},"required":["username"]},"example":{"username":"natgeo","limit":10}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/threads/v1/replies":{"post":{"operationId":"threads_replies","summary":"Public replies from a Threads profile (the Replies tab)","description":"Public replies from a Threads profile (the Replies tab). Set `limit` for how many to return.","tags":["threads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","example":"zuck","description":"Threads handle without the @ (the name in threads.com/@<username>)."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25,"description":"Max items to return (1-100). Larger values are clamped to 100."}},"required":["username"]},"example":{"username":"zuck","limit":10}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/threads/v1/reposts":{"post":{"operationId":"threads_reposts","summary":"Posts a Threads user has reposted — the Reposts tab on their profile","description":"Posts a Threads user has reposted — the Reposts tab on their profile. Returns the original reposted posts (authored by other accounts).","tags":["threads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","example":"zuck","description":"Threads handle without the @ (the name in threads.com/@<username>)."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25,"description":"Max items to return (1-100). Larger values are clamped to 100."}},"required":["username"]},"example":{"username":"natgeo","limit":10}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/threads/v1/post":{"post":{"operationId":"threads_post","summary":"Maximally-complete public post detail","description":"Maximally-complete public post detail. Provide url, or username + code, or post_id. Returns text, media (image/video/carousel), all engagement counts, location, music, tagged users, link preview, language and paid-partnership flag.","tags":["threads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","example":"https://www.threads.com/@zuck/post/C8H9mn_xyz1","description":"Full Threads post URL (alternative to username + code)."},"username":{"type":"string","example":"zuck","description":"Threads handle without the @ (the name in threads.com/@<username>)."},"code":{"type":"string","example":"C8H9mn_xyz1","description":"Post shortcode — the code in threads.com/@<username>/post/<code>. Combine with username, or pass the full post `url` instead."},"post_id":{"type":"string","example":"3141592653589793238","description":"Numeric Threads post id (from a post's `id`). Alternative to url / username+code."}}},"example":{"username":"natgeo","code":"DZ2pt10Eanh"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/threads/v1/post_replies":{"post":{"operationId":"threads_post_replies","summary":"The reply conversation for a public post (thread_items)","description":"The reply conversation for a public post (thread_items). Provide post_id, or url, or username + code.","tags":["threads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"post_id":{"type":"string","example":"3141592653589793238","description":"Numeric Threads post id (from a post's `id`). Alternative to url / username+code."},"url":{"type":"string","example":"https://www.threads.com/@zuck/post/C8H9mn_xyz1","description":"Full Threads post URL (alternative to username + code)."},"username":{"type":"string","example":"zuck","description":"Threads handle without the @ (the name in threads.com/@<username>)."},"code":{"type":"string","example":"C8H9mn_xyz1","description":"Post shortcode — the code in threads.com/@<username>/post/<code>. Combine with username, or pass the full post `url` instead."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25,"description":"Max items to return (1-100). Larger values are clamped to 100."}}},"example":{"username":"natgeo","code":"DZ2pt10Eanh","limit":10}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/threads/v1/search":{"post":{"operationId":"threads_search","summary":"Search public Threads posts by keyword","description":"Search public Threads posts by keyword. Returns matching public posts with author, text and permalink.","tags":["threads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","example":"reef","description":"Search keyword (also accepted as 'query')."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":25,"example":25,"description":"Max items to return (1-50). Larger values are clamped to 50."}},"required":["q"]},"example":{"q":"reef","limit":10}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":2}},"/threads/v1/user_search":{"post":{"operationId":"threads_user_search","summary":"Look up the public Threads account whose handle matches a query (exact / near-exact)","description":"Look up the public Threads account whose handle matches a query (exact / near-exact). NOTE: full fuzzy people search is login-gated by Threads; logged-out resolves the matching handle, like instagram's users_search.","tags":["threads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","example":"reef","description":"Search keyword (also accepted as 'query')."}},"required":["q"]},"example":{"q":"natgeo"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/threads/v1/followers":{"post":{"operationId":"threads_followers","summary":"Account-gated: the followers list requires a logged-in Threads session and is not available for public (logged-out) use.","description":"Account-gated: the followers list requires a logged-in Threads session and is not available for public (logged-out) use.","tags":["threads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","example":"zuck","description":"Threads handle without the @ (the name in threads.com/@<username>)."}}},"example":{"username":"zuck"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/threads/v1/following":{"post":{"operationId":"threads_following","summary":"Account-gated: the following list requires a logged-in Threads session and is not available for public (logged-out) use.","description":"Account-gated: the following list requires a logged-in Threads session and is not available for public (logged-out) use.","tags":["threads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","example":"zuck","description":"Threads handle without the @ (the name in threads.com/@<username>)."}}},"example":{"username":"zuck"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/threads/v1/likes":{"post":{"operationId":"threads_likes","summary":"Account-gated: the list of accounts that liked a post (who-liked) is not exposed to logged-out clients by Threads — it requires a logged-in session.","description":"Account-gated: the list of accounts that liked a post (who-liked) is not exposed to logged-out clients by Threads — it requires a logged-in session.","tags":["threads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","example":"https://www.threads.com/@zuck/post/C8H9mn_xyz1","description":"Full Threads post URL (alternative to username + code)."},"username":{"type":"string","example":"zuck","description":"Threads handle without the @ (the name in threads.com/@<username>)."},"code":{"type":"string","example":"C8H9mn_xyz1","description":"Post shortcode — the code in threads.com/@<username>/post/<code>. Combine with username, or pass the full post `url` instead."},"post_id":{"type":"string","example":"3141592653589793238","description":"Numeric Threads post id (from a post's `id`). Alternative to url / username+code."}}},"example":{"url":"https://www.threads.com/@zuck/post/C8H9mn_xyz1"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Envelope":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"data":{"description":"Action result (shape varies per action)"},"meta":{"type":"object","description":"api, endpoint, mode, latency_ms, record_count, completeness_pct"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}