> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Threads API

> 搜索 Threads，并以 JSON 读取公开的个人主页、帖子和回复，包括点赞、回复、转发、引用、分享数和发布时间。

通过异步任务 API 以 JSON 读取公开的 Threads 数据。发送 `taskType` `SOCIAL` 并设置 `platform` `threads`，用 `action` 选择要读取的内容。每次完成的请求消耗 **0.5 积分**。

## 请求

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "SOCIAL", "payload": { "platform": "threads", "action": "search", "query": "running shoes", "limit": 20 } }'
```

提交任务后，轮询 `GET /v1/async/task/{id}` 或通过 webhook 接收。参见[异步任务](https://docs.querying.ai/zh/concepts/async-tasks.md)。

## 操作

| `action` | 读取内容 | 必填 |
| - | - | - |
| `search`（默认） | 某个关键词的帖子 | `query` |
| `profile` | 公开个人主页及其最新帖子 | `username` |
| `post` | 一条帖子 | `postUrl` |
| `replies` | 帖子的回复 | `postUrl` |

`username` 接受用户名或个人主页 URL。`postUrl` 接受帖子 URL，例如 `https://www.threads.com/@natgeo/post/Dfzi22JJSYp`。

## 参数

* `query`：`search` 必填。
* `limit`：可选。`search` 和 `profile` 范围 1-50，默认 10。`replies` 范围 1-500，默认 50。

## 响应示例

```json theme={"theme":"css-variables"}
{
  "platform": "threads",
  "action": "search",
  "query": "running shoes",
  "returnedCount": 1,
  "posts": [
    {
      "id": "4032816753373504516",
      "code": "Df3cXhtEmQE",
      "url": "https://www.threads.com/@bongdgzmn/post/Df3cXhtEmQE",
      "text": "Gave in to the hype as I am also looking for a new pair of daily running shoes.",
      "author": "bongdgzmn",
      "authorVerified": false,
      "publishedAt": "2026-11-18T02:34:01.000Z",
      "mediaType": "carousel",
      "likeCount": 62,
      "replyCount": 42,
      "repostCount": 1,
      "quoteCount": 0,
      "shareCount": 19,
      "isReply": false
    }
  ]
}
```

## 结果字段

* 每个响应都会原样返回 `platform` 和 `action`。列表带有 `returnedCount`。
* 帖子包含 `id`、`code`、`url`、`text`、`author`、`authorVerified`、`publishedAt`、`mediaType`（`text`、`image`、`video` 或 `carousel`）、`images`、`videoUrl`、`likeCount`、`replyCount`、`repostCount`、`quoteCount`、`shareCount` 和 `isReply`。回复还会加上 `replyTo`，即被回复的用户名。
* `search` 按 Threads 显示的顺序返回 `posts`，最多约 50 条。
* `profile` 返回 `id`、`username`、`displayName`、`biography`、`bioLinks`、`avatarUrl`、`profileUrl`、`isVerified`、`isPrivate`、`followerCount`、`threadCount` 和 `recentPosts`，即个人主页显示的最新 4-13 条帖子。
* `post` 返回 `post`。`replies` 返回 `replies`，每条帖子约 10 条。`availableCount` 是帖子的回复数，`partial: true` 表示列表短于该数量，例如作者隐藏了回复。
* 不存在或未公开的个人主页或帖子会使任务以 `PAGE_UNAVAILABLE` 结束。只对完成的请求计费。

## 相关

* [Instagram](https://docs.querying.ai/zh/engines/instagram.md)
* [YouTube](https://docs.querying.ai/zh/engines/youtube.md)
* [引擎概览](https://docs.querying.ai/zh/engines/overview.md)
* [积分与限制](https://docs.querying.ai/zh/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.