# Threads 关键词搜索 API (threads.search)

- Canonical page: https://everyinfra.com/threads-api/search
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "threads", "action": "search", "params": {...}}
- Price: $0.000778 per call ($0.78 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 15, max 50 per call
- Mode: sync; add "mode": "async" for slow tasks

Threads 关键词搜索按 `keyword` 检索公开的 Threads 帖子，每条带正文全文、链接、点赞和评论数、发布时间，以及作者的昵称、用户名和 `author_id`。它回答「Threads 上的人怎么谈论这个话题、品牌或新品」，适合品牌、公关和研究团队监测讨论、为情感分析收集帖子，或者找出常发这个主题的账号。

它搜的是帖子，不是账号。按 `author_id` 给结果分组，能看出谁在这个话题上发帖最多；每行都保留 `url`，方便日后引用原帖。`posted_at` 是 UTC 时间，`like_count`、`comment_count` 为 null 表示没有公开，不等于 0。

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=threads&action=search

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| keyword | not declared | yes | not declared | search 搜索公开帖子，discover_profiles 用关键词发现创作者；后者是异步任务，不能把响应任务状态当成已返回账号名单。 |
| limit | integer (1–50) | no | 15 | 这次调用最多返回的条数，整数，1–50；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | 该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。 |
| url | 该记录在原平台上的可访问链接。 |
| text | 正文内容，已去除 HTML 标签，全文返回、不截断（个别平台的列表结果本身只有摘要，以该平台的字段说明为准）。 |
| author_name | 作者昵称（显示名）。 |
| author_username | 作者用户名（@handle），通常可用于拼 URL。 |
| author_id | 作者在原平台的唯一 ID。 |
| like_count | 点赞数。null 表示该平台或该接口不公开此数据，不等于 0。 |
| comment_count | 评论数。null 表示不公开，不等于 0。 |
| posted_at | 发布时间，ISO 8601 格式、UTC 时区（如 2026-08-07T12:34:56+00:00）。平台只给非标准字符串时原样透传，解析前建议做容错。null 表示平台未公开。 |
| author_is_verified | 作者是否已认证。 |
| media | 帖子的图片 / 视频：type、url、width、height。 |
| hashtags | 正文里的话题标签数组，按出现顺序；没有时不出现这个字段。 |
| mentions | 正文里 @ 到的用户名。 |
| links | 正文里的外链。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "threads",
  "action": "search",
  "params": {
    "keyword": "indie development"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "threads",
        "action": "search",
        "params": {
            "keyword": "indie development",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-09-26T08:56:04Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 25. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "threads",
  "action": "search",
  "results": [
    {
      "id": "•••",
      "url": "https://threads.com/t/DdvXgRHjJAi",
      "text": "Kyiv has long requested additional Patriot systems and manufacturing access to improve protection against Russian ballistic missile attacks. The Kremlin said it is closely monitoring which countries provide weapons and production licenses to Ukraine. Trump had previously supporte…",
      "author_name": "•••",
      "author_username": "•••",
      "author_id": "•••",
      "like_count": 0,
      "comment_count": 1,
      "posted_at": "2026-09-26T06:14:49+00:00",
      "platform": "threads"
    },
    {
      "id": "•••",
      "url": "https://threads.com/t/DdvXgtqjKTo",
      "text": "The latest statement may therefore represent a significant development in #USUkraine cooperation while diplomatic discussions on de escalation remain active. #Geopolitics #Defense #Diplomacy #NATO #Trump #Zelensky\n\n✦\nIt is not just about quality, it is about identity. I compose o…",
      "author_name": "•••",
      "author_username": "•••",
      "author_id": "•••",
      "like_count": 0,
      "comment_count": 0,
      "posted_at": "2026-09-26T06:14:52+00:00",
      "platform": "threads"
    }
  ],
  "count": 25,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### 能用它找账号吗？

不能。Threads 关键词搜索返回的是帖子。按主题找创作者请用 Threads 账号发现，它同样接受关键词，但以异步任务运行：第一次响应是任务状态，不是账号名单，任务完成后才能取到账号。

### 怎么从帖子找到作者？

`author_username` 是作者的用户名，传给 Threads 主页或对象详情可以读主页资料，传给 Threads 用户内容可以读他的更多帖子，两者都只收用户名，不解析完整主页链接。`author_name` 是显示昵称，不能用来查账号。

### 能按时间范围筛选吗？

这个能力只接受 `keyword`，没有日期参数。需要近期帖子时，调用后按 `posted_at` 自行过滤；它是 UTC 的 ISO 8601 时间，平台给出非标准时间字符串时会原样透传，解析时要做容错。

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=threads
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md