Threads keyword search API

Parameters from the 2026-10-25 specification snapshot; response rows checked against live responses on 2026-11-21

Quick answer

POST /threads/search/task starts an asynchronous search of public Threads posts for one keyword, optionally narrowed by account_username, start_date and end_date (both inclusive) and max_scroll. Poll GET /threads/search/task/{task_id}: the response carries the task status and counters, the posts collected so far in data and their number in total_count. Each post has its URL, native post ID, author, text, timestamps, like, reply and share counts, media URLs, and flags for replies and quote posts. You authenticate with your LargitData API key, not a Threads access token. Data is collected by web crawlers from content publicly published on Threads.

What teams use it for

  • Track how a brand, product or public issue is discussed on Threads, and pull the posts behind a spike.
  • Build a dated set of posts on a topic for market or academic research, with engagement counts to rank them.
  • Pass post URLs to the replies and reactions endpoints to see how a single post was received.

Endpoints

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

MethodPathWhat it does
POST /threads/search/task Creates a keyword search task, with optional account name, date range, max_scroll and rerun.
GET /threads/search/task/{task_id} Polls a search task: status, the completed, total, failed_articles and failed_pages counters, and the posts collected so far in data with total_count.

Request parameters

POST /threads/search/task

ParameterInTypeRequiredDefault / allowedDescription
keyword body string Yes Search keyword.
account_username body string No Optional Threads username.
end_date body string No End of the date range, inclusive (YYYY-MM-DD). Ignored if start_date is missing.
mask_author body boolean No false Set to true to remove author identity fields from this response. Send it on each GET poll to mask the returned rows.
max_scroll body integer No Scroll limit for the crawl. Non-negative integer.
rerun body boolean No Boolean; run the collection again.
start_date body string No Start of the date range, inclusive (YYYY-MM-DD).

GET /threads/search/task/{task_id}

ParameterInTypeRequiredDefault / allowedDescription
task_id path string Yes Task ID returned when the task was created.
mask_author query boolean No false Set to true to remove author identity fields from this response. Send it on each GET poll to mask the returned rows.

Response fields

DataFieldsEndpoint
Posts id, post_id, url, root_post_id, root_post_url, parent_id, parent_url, author, author_id, author_name, content, tm, tm_crawler, like_count, reaction_count, comment_count, share_count, is_reply, is_quote, reply_to_author, metadata_img, metadata_videos, tag, keyword, source GET /threads/search/task/{task_id}

Code examples

curl: create the 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}'

curl: poll the task by ID

curl "https://api.infominer.io/api/v2/threads/search/task/$TASK_ID?page=1&per_page=1000" \
  -H "auth-header: YOUR_API_KEY"

Python (requests): create, poll, read

import time
import requests

BASE_URL = "https://api.infominer.io/api/v2"
HEADERS = {"auth-header": "YOUR_API_KEY"}

# 1. Create the task
resp = requests.post(
    f"{BASE_URL}/threads/search/task",
    headers=HEADERS,
    json={
        "keyword": "登山步道",
        "start_date": "2026-06-01",
        "end_date": "2026-06-30",
        "max_scroll": 5,
        "mask_author": False,
    },
    timeout=30,
)
resp.raise_for_status()
task = resp.json()

# 2. Poll until the task leaves INIT / RUNNING
for _ in range(120):
    resp = requests.get(
        f"{BASE_URL}/threads/search/task/{task['id']}",
        headers=HEADERS,
        params={
            "page": 1,
            "per_page": 1000,
        },
        timeout=30,
    )
    resp.raise_for_status()
    result = resp.json()
    status = result.get("status") or result.get("task", {}).get("status")
    if status not in ("INIT", "RUNNING"):
        break
    time.sleep(15)
else:
    raise SystemExit("task still running; poll it again later")

if status == "FAILED":
    raise SystemExit("task failed")
if status != "DONE":
    print("task ended with status", status, "- results may be incomplete")

# 3. Read the records (use page / per_page to fetch further pages)
for row in result.get("data", []):
    print(row.get("url"), (row.get("content") or "")[:60])

Sample response

Illustrative data written by hand: accounts are sample_user_n and IDs are obviously fake. Field names follow live API responses checked on 2026-11-21; the sample shows a subset of the fields.

Poll response once the task is DONE (illustrative data)

{
  "id": "00000000-0000-4000-8000-000000000001",
  "keyword": "登山步道",
  "status": "DONE",
  "start_date": "2026-06-01",
  "end_date": "2026-06-30",
  "total": 2,
  "completed": 2,
  "partial": false,
  "timed_out": false,
  "failed_articles": 0,
  "failed_pages": 0,
  "total_count": 2,
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000003",
      "source": "threads",
      "keyword": "登山步道",
      "post_id": "00000000001",
      "url": "https://www.threads.com/@sample_user_1/post/00000000001",
      "root_post_id": "00000000001",
      "root_post_url": "https://www.threads.com/@sample_user_1/post/00000000001",
      "author": "sample_user_1",
      "author_id": "0000000001",
      "content": "週末走了一條不太熱門的步道,沿途視野很開闊,建議早點出發避開人潮",
      "tm": 1781056800,
      "tm_crawler": 1781143200,
      "like_count": 34,
      "reaction_count": 34,
      "comment_count": 4,
      "share_count": 1,
      "is_reply": false,
      "is_quote": false,
      "reply_to_author": "",
      "metadata_img": [],
      "metadata_videos": [],
      "tag": ""
    },
    {
      "id": "00000000-0000-4000-8000-000000000004",
      "source": "threads",
      "keyword": "登山步道",
      "post_id": "00000000002",
      "url": "https://www.threads.com/@sample_user_2/post/00000000002",
      "root_post_id": "00000000001",
      "root_post_url": "https://www.threads.com/@sample_user_1/post/00000000001",
      "parent_id": "00000000001",
      "parent_url": "https://www.threads.com/@sample_user_1/post/00000000001",
      "author": "sample_user_2",
      "author_id": "0000000002",
      "content": "請問這條步道雨天好走嗎?下週想安排家人一起去",
      "tm": 1781060400,
      "tm_crawler": 1781143200,
      "like_count": 3,
      "reaction_count": 3,
      "comment_count": 1,
      "share_count": 0,
      "is_reply": true,
      "is_quote": false,
      "reply_to_author": "sample_user_1",
      "metadata_img": [],
      "metadata_videos": [],
      "tag": ""
    }
  ]
}

Limits and notes

  • start_date and end_date are inclusive. If you pass end_date without start_date, the upstream ignores it and applies its default range.
  • max_scroll must be a non-negative integer.
  • The poll response includes the rows collected so far, so data can be read while the task is still RUNNING.
  • Poll responses are paginated: send page and per_page on the GET request (per_page defaults to 1000, the maximum). Each response reports page, per_page and total_count, the number of rows collected so far; read further pages until you have total_count rows.
  • How far back search can go, volume per task 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.

More Threads API pages

Request a trial

In the request form below, mention Threads 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 reply with the arrangements for the trial and API key.

Fill in the form to request a trial. We confirm the scope and reply with trial and integration arrangements.

Fill in the request form

FAQ

How is this different from keyword search in Meta's Threads API?
Meta's Threads API keyword search is called with a Threads user access token and needs the threads_keyword_search permission; until Meta approves that permission in app review, it only searches the authenticated user's own posts. This endpoint is a separate service: it returns publicly published posts collected by LargitData's web crawlers, under the API key LargitData issues to you.
Does the search return replies as well as top-level posts?
Yes. A search row can be a reply: it then has is_reply set to true, reply_to_author, and parent_id, parent_url, root_post_id and root_post_url pointing at the post it answers and the thread it belongs to.
Can I leave author information out of the results?
Yes for the author fields. Add mask_author=true to each GET poll request: author, author_id, author_name and reply_to_author are removed from that response. url is kept, and a Threads post URL contains the account handle, so drop url as well if handles must not be stored.
How is the data collected? Is this the official Threads API?
By web crawlers, from content publicly published on Threads. LargitData is not affiliated with Meta or Threads, and this is not Meta's Threads API. Whether this suits your use depends on the purpose and jurisdiction and is for your legal team to assess; we can provide a description of sources and collection methods.