Threads API: post search, replies and reactions tasks

Based on the 2026-10-25 specification snapshot

Quick answer

The Threads API has four asynchronous task types: keyword search, the replies to one post (pushs), public account timelines, and post reactions. A reactions task that completes successfully returns the reactions list with pagination in its poll response. Search, reply and timeline polls return status and counters only; how results are retrieved for your account (through the search endpoint or a project dataset) is confirmed at onboarding. Every endpoint accepts mask_author to remove author identity fields. Data is collected by web crawlers from content publicly published on Threads.

Data you get

Fields follow the 2026-10-25 specification snapshot. The snapshot does not enumerate search-result post fields, so rows marked "illustrative sample" are taken from the sample data below; confirm the production fields against your trial data. The snapshot also does not mark linking fields such as post_id and parent_id as required, so confirm their presence with trial data.

DataFieldsEndpoint
Search task status id, status, completed, total, failed_articles, failed_pages, partial, timed_out, created_at, keyword, account_username GET /threads/search/task/{task_id}
Reply task status id, status, completed, total, failed_articles, failed_pages, partial, timed_out, created_at, post_url GET /threads/pushs/task/{task_id}
Public account timeline task status id, status, completed, total, failed_articles, failed_pages, partial, timed_out, created_at, author_id GET /threads/users/task/{task_id}
Post reactions data, pagination, error_message, task.post_id, task.post_url, task.status, task.warnings GET /threads/reactions/task/{task_id}
Result records (illustrative sample; retrieval confirmed at onboarding) id, url, author, content, tm, like_count, comment_count, share_count, reply_count, is_reply, is_quote, reply_to_author Confirmed at onboarding

Endpoints

Base URL: https://api.infominer.io/api/v2. Send your API key in the auth-header request header. Parameters marked * are required.

MethodPathWhat it doesMain parameters
POST /threads/search/task Creates a keyword search task, with optional account name, date range, max_scroll and rerun. keyword* account_username end_date mask_author max_scroll rerun start_date
GET /threads/search/task/{task_id} Polls a search task for status and the completed, total, failed_articles and failed_pages counters; result rows are not included. task_id* mask_author
POST /threads/pushs/task Creates a reply collection task from a post URL. post_url* mask_author max_scroll rerun
GET /threads/pushs/task/{task_id} Polls a reply task for status and counters; reply rows are not included. task_id* mask_author
POST /threads/users/task Creates a public account timeline task with an optional date range. author_id* end_date mask_author max_scroll rerun start_date
GET /threads/users/task/{task_id} Polls a timeline task for status and counters; post rows are not included. task_id* mask_author
POST /threads/reactions/task Creates a reactions collection task from a post URL; rerun defaults to true. post_url* mask_author rerun
GET /threads/reactions/task/{task_id} Polls a reactions task; on success it returns the reactions list with pagination. task_id* page per_page mask_author

How to get the data

  1. POST /threads/search/task with keyword (required) and optional account_username, start_date, end_date (inclusive), max_scroll (non-negative) and rerun.
  2. Poll GET /threads/search/task/{task_id} for the status (INIT, RUNNING, DONE, PARTIAL, TIMED_OUT or FAILED) and the completed, total, failed_articles and failed_pages counters.
  3. For the replies to a post, POST /threads/pushs/task with post_url. For reactions, POST /threads/reactions/task with post_url (rerun defaults to true, so sending the same URL again starts a fresh task).
  4. When a reactions task is DONE and neither partial nor timed out, GET /threads/reactions/task/{task_id} returns data and pagination, with per_page up to 1000; if the task succeeded but the list could not be fetched, the response carries error_message.
  5. Search, reply and timeline results are not included in the poll response; how they are retrieved for your account (through the search endpoint or a project dataset) is confirmed at onboarding.

curl examples

Create a keyword search task

curl -X POST https://api.infominer.io/api/v2/threads/search/task \
  -H "auth-header: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "登山步道", "start_date": "2026-06-01", "end_date": "2026-06-30", "max_scroll": 5, "mask_author": false}'

Poll the task by ID

curl "https://api.infominer.io/api/v2/threads/search/task/$TASK_ID" \
  -H "auth-header: YOUR_API_KEY"

Create a reactions task with author fields masked

curl -X POST https://api.infominer.io/api/v2/threads/reactions/task \
  -H "auth-header: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"post_url": "https://www.threads.com/@sample_user_1/post/SAMPLE000001", "mask_author": true}'

Sample JSON

Illustrative data written by hand: accounts are sample_user_n and IDs are obviously fake. These are not real posts.

Task creation response (Illustrative data)

{
  "id": "00000000-0000-4000-8000-000000000001",
  "keyword": "登山步道",
  "status": "INIT",
  "start_date": "2026-06-01",
  "end_date": "2026-06-30",
  "max_scroll": 5,
  "rerun": false,
  "partial": false,
  "timed_out": false,
  "completed": null,
  "total": null,
  "failed_articles": 0,
  "failed_pages": 0,
  "created_at": 1781056800
}
Threads search polls return status and counters only. The records below are illustrative and show the shape of the fields; how results are retrieved for your account is confirmed at onboarding.

Result records (Illustrative data, not a poll response)

{
  "total_count": 2,
  "data": [
    {
      "id": "00000000-0000-4000-8000-0000000000a1",
      "source": "threads",
      "url": "https://www.threads.com/@sample_user_1/post/SAMPLE000001",
      "author": "sample_user_1",
      "title": "",
      "content": "週末走了一條不太熱門的步道，沿途視野很開闊，建議早點出發避開人潮",
      "tm": 1781056800,
      "sentiment": "Positive",
      "like_count": 34,
      "comment_count": 4,
      "share_count": 1,
      "reply_count": 4,
      "is_reply": false,
      "is_quote": false,
      "reply_to_author": "",
      "search_type": "keyword",
      "tag": "",
      "tag_id": ""
    },
    {
      "id": "00000000-0000-4000-8000-0000000000a2",
      "source": "threads",
      "url": "https://www.threads.com/@sample_user_2/post/SAMPLE000002",
      "author": "sample_user_2",
      "title": "",
      "content": "請問這條步道雨天好走嗎？下週想安排家人一起去",
      "tm": 1781060400,
      "sentiment": "Neutral",
      "like_count": 3,
      "comment_count": 1,
      "share_count": 0,
      "reply_count": 1,
      "is_reply": true,
      "is_quote": false,
      "reply_to_author": "sample_user_1",
      "search_type": "keyword",
      "tag": "",
      "tag_id": ""
    }
  ]
}

How posts and comments link

Reply and reactions tasks are both created from the post URL (post_url). A reactions task fills in the post's native ID (post_id) once it has crawled, and it is null before that. In the illustrative result records, replies are marked with is_reply and reply_to_author, quotes with is_quote, and reply_count gives the number of replies. With mask_author=true the author identity fields are removed, but url and post_url are kept, so records still link back to their post.

History and limits

  • Search, reply and public account timeline tasks: polls return status and counters only, and result retrieval is confirmed per account at onboarding.
  • If you pass end_date without start_date, the upstream ignores that input and applies its default range.
  • Reactions per_page is capped at 1000; if the task succeeded but the list could not be fetched, the response carries error_message.
  • max_scroll must be an integer, and non-negative for search tasks.
  • How far back you can go and refresh frequency are confirmed per project scope.
Collection: web crawlers collect content publicly published on each platform. Whether this suits your use depends on the purpose and jurisdiction and is for the buyer's legal team to assess; we can provide a description of sources and collection methods.

Delivery format

Task status and reactions are returned as JSON. The delivery route for search, reply and timeline results (the search endpoint or a project dataset) is confirmed per account at onboarding; batch files or other delivery methods are confirmed per project scope.

Request a trial

Tick Threads in the form below and tell us the keywords or accounts, whether you need replies and reactions, and whether author fields should be masked. We confirm the scope and how results are retrieved, and reply with the arrangements for the trial and API key.

We use the details you provide only to reply to this inquiry. See our privacy policy. Or email us at [email protected]

FAQ

Can the Threads API return the reactions to a post?
Yes. POST /threads/reactions/task with the post URL; once the task succeeds, GET returns the reactions list with pagination.
Where do I get Threads search results after the task finishes?
Search polls return status and counters only. How results are retrieved for your account (through the search endpoint or a project dataset) is confirmed at onboarding.
Can I leave author information out of responses?
Yes. Pass mask_author=true when creating or polling; author identity fields are removed and url and post_url are kept.
How do I collect the posts of a public account?
Use /threads/users/task with author_id (a leading @ is optional), plus optional start_date and end_date.
How is the Threads data collected?
By web crawlers, from content publicly published on Threads. Whether this suits your use depends on the purpose and jurisdiction and is for the buyer's legal team to assess; we can provide a description of sources and collection methods.