# Threads 推荐流 API (threads.feed)

- Canonical page: [https://everyinfra.com/threads-api/feed](https://everyinfra.com/threads-api/feed?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "threads", "action": "feed", "params": {...}}
- Price: $0.000556 per call ($0.56 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, one page of 10 per call (limit is ignored; pass the top-level next_page_token from the response as page_token for the next page)
- Pagination: pass next_page_token back as page_token for the next page, other params unchanged; one call per page, tokens last 24 hours
- Mode: sync; add "mode": "async" for slow tasks

## Health

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

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| page_token | not declared | no | not declared | 翻页令牌。第一页不传；响应有 next_page_token 时原样作 page_token 传回，其他参数不变。一页最多 10 条，limit 不起作用。每页算一次调用；令牌 24 小时有效。没有 next_page_token 就是翻不下去了。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | 该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。 |
| code | 内容短码，用于拼 URL。 |
| url | 该记录在原平台上的可访问链接。 |
| text | 正文内容，已去除 HTML 标签，全文返回、不截断（个别平台的列表结果本身只有摘要，以该平台的字段说明为准）。 |
| author_username | 作者用户名（@handle），通常可用于拼 URL。 |
| author_name | 作者昵称（显示名）。 |
| author_id | 作者在原平台的唯一 ID。 |
| author_avatar_url | 作者头像图片链接（多数平台带签名、会过期）。 |
| author_is_verified | 作者是否已认证。 |
| author_is_private | 作者账号是否私密。 |
| author_follower_count | 作者粉丝数。null 表示不公开。 |
| like_count | 点赞数。null 表示该平台或该接口不公开此数据，不等于 0。 |
| comment_count | 评论数。null 表示不公开，不等于 0。 |
| repost_count | 转发数（区别于引用转发）。null 表示不公开。 |
| quote_count | 引用数：别人引用这条帖子发帖的次数。null 表示不公开，不等于 0。 |
| share_count | 分享/转发数。null 表示不公开，不等于 0。 |
| posted_at | 发布时间，ISO 8601 格式、UTC 时区（如 2026-08-07T12:34:56+00:00）。平台只给非标准字符串时原样透传，解析前建议做容错。null 表示平台未公开。 |
| media_type | 帖子类型：text 纯文字、image 单图、video 单视频、carousel 多图，或图片和视频混合。 |
| image_count | 图片张数。 |
| video_count | 视频个数。 |
| media_url | 第一个附件的地址，带签名，会过期。 |
| video_duration_seconds | 第一个视频的时长，秒；每个视频各自的时长在 media 每一项的 duration_seconds。 |
| topic | 帖子挂的话题的内部名，如 bakingthreads；显示名在 topic_name。 |
| topic_id | 帖子挂的话题的编号。 |
| topic_name | 话题的显示名，如 Baking Threads。 |
| topic_emoji | 话题（社区）的表情图标。 |
| topic_is_community | 话题是否为社区。 |
| language | 内容语言代码（如 zh、en），由平台判定，可能不准。 |
| is_edited | 帖子是否编辑过。 |
| is_reply | 这条帖子是否为回复。 |
| reply_to_username | 这条帖子回复的是谁（用户名）；不是回复时不出现。 |
| root_post_author_username | 这串对话最上面那条帖子的作者用户名。 |
| reply_level | 回复层级：1 是直接回复主帖，2 是回复的回复，以此类推。 |
| is_pinned | 是否被作者置顶在主页。 |
| is_pinned_by_author | 只在回复上出现：是否被主帖作者置顶在回复区。 |
| is_spoiler | 是否标了剧透遮罩。 |
| reply_control | 谁能回复这条帖子，如 everyone。 |
| counts_hidden | 作者是否隐藏了点赞数和分享数；隐藏时 like_count 为 null。 |
| thread_id | 作者连发的这一串帖子的编号，同一串的帖子这个值相同。 |
| thread_length | 作者连发的这一串一共几条；不是连发时为 1。 |
| thread_position | 这条是连发串里的第几条。 |
| is_federated | 是否同步到联邦宇宙（Fediverse）。 |
| is_paid_partnership | 是否标注为付费合作内容。识别广告用。 |
| ai_label | AI 生成内容的标注方式，如 SELF_DISCLOSURE_FLOW（作者自己标的）；没标注时不出现。 |
| text_translation | Threads 给的正文英文翻译；正文不是英语、平台又给了翻译时才有。 |
| attached_text | 帖子挂的长文附件（Threads 的文字附件）的全文。 |
| fediverse_like_count | 联邦宇宙（Mastodon 等）那边的点赞数。 |
| fediverse_reply_count | 联邦宇宙那边的回复数。 |
| is_liked_by_author | 只在回复上出现：这条回复有没有被主帖作者点赞。 |
| is_collapsed | 只在回复上出现：这条回复被平台折叠了；是的时候才出现。 |
| reply_approval_enabled | 作者开了「回复要先审核」；是的时候才出现。 |
| is_ghost_post | 是限时帖（过一段时间自动消失）；是的时候才出现。 |
| ghost_expires_at | 限时帖消失的时间。 |
| is_markup | 是在别人帖子上涂画批注的帖子；是的时候才出现。 |
| hashtags | 正文里的话题标签数组，按出现顺序；没有时不出现这个字段。 |
| mentions | 正文里 @ 到的用户名。 |
| links | 正文里的链接和帖子挂的链接。 |
| image_urls | 帖子的全部图片地址。 |
| video_urls | 全部视频地址，带签名，会过期。 |
| tagged_users | 图片、视频里被标记的人（用户名）。 |
| media | 附件列表，一个附件一项；没有附件时不出现。每项：type（image 或 video）、url（文件地址，带签名，会过期）、width、height（像素）、alt_text（替代文字，Threads 自动生成或作者填写），视频另有 thumbnail_url（封面）、has_audio（有没有声音）、duration_seconds（时长，秒）。 |
| link_preview | 链接卡片：url、title（卡片标题）、description（卡片描述）、display_url（显示的域名）、image_url（配图）、favicon_url（网站小图标）。 |
| location | 帖子挂的地点：id（地点编号）、name（地点名）、url（Threads 上这个地点的页面）。 |
| quoted_post | 这条帖子引用的原帖：id、code、url、text、author_username、posted_at。 |
| reposted_post | 这条帖子转发的原帖，结构同 quoted_post。 |
| gif | 帖子里的 GIF：url、webp_url（WebP 格式的地址）、width、height（像素）。 |
| music | 帖子配的音乐：song_id、title（歌名）、artist（歌手）、cover_url（封面）、start_ms（从歌曲第几毫秒开始播）；不含歌词。 |
| podcast | 帖子上挂的播客单集卡：episode_name、episode_url、podcast_name、platform（播客平台，如 SPOTIFY、APPLE）、image_url。账号资料（profile）里是主页挂的播客：name、url、platform、image_url，有的还带 links（各平台的收听链接，每项 platform、url）。 |
| scorecard | 帖子挂的体育比分卡：status（upcoming 未开始、live 进行中、past 已结束）、starts_at（开赛时间）、clock（比赛时钟）、period（第几节，如 Q4）、home_team、away_team（主队、客队，各带 name、short_name、score、logo_url）、url（卡片底部的链接）。 |
| trend | 这条帖子上了哪个趋势：keyword（趋势的搜索词）、id、summary（平台写的摘要，有的才带）。 |
| author_badge | 作者在这个社区里的徽章：type（徽章类型，如 MEMBER）、label（作者在社区里选的身份标签，如球队名）。 |
| custom_like | 这条帖子换掉默认爱心的自定义点赞样式：type（EMOJI 或 STICKER）、emoji、sticker_url（贴纸 GIF 地址）。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |
| in_reply_to | 这条回复回的是哪条帖子：id、code、url、text、author_username、author_name、like_count、comment_count、posted_at。 |
| reposted_by | 转发这条帖子的账号（用户名）；这一行本身是被转发的原帖。 |
| reposted_at | 转发的时间。 |

## 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": "feed",
  "params": {}
}'
```

```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": "feed",
        "params": {},
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

No real sample for these example parameters yet: structure only, every value is a placeholder (…).

```text
{
  "id": "req_…",
  "platform": "threads",
  "action": "feed",
  "results": [
    {
      "id": …,
      "code": …,
      "url": …,
      "text": …,
      "author_username": …,
      "author_name": …,
      "author_id": …,
      "author_avatar_url": …,
      "author_is_verified": …,
      "author_is_private": …,
      "author_follower_count": …,
      "like_count": …,
      "comment_count": …,
      "repost_count": …,
      "quote_count": …,
      "share_count": …,
      "posted_at": …,
      "media_type": …,
      "image_count": …,
      "video_count": …,
      "media_url": …,
      "video_duration_seconds": …,
      "topic": …,
      "topic_id": …,
      "topic_name": …,
      "topic_emoji": …,
      "topic_is_community": …,
      "language": …,
      "is_edited": …,
      "is_reply": …,
      "reply_to_username": …,
      "root_post_author_username": …,
      "reply_level": …,
      "is_pinned": …,
      "is_pinned_by_author": …,
      "is_spoiler": …,
      "reply_control": …,
      "counts_hidden": …,
      "thread_id": …,
      "thread_length": …,
      "thread_position": …,
      "is_federated": …,
      "is_paid_partnership": …,
      "ai_label": …,
      "text_translation": …,
      "attached_text": …,
      "fediverse_like_count": …,
      "fediverse_reply_count": …,
      "is_liked_by_author": …,
      "is_collapsed": …,
      "reply_approval_enabled": …,
      "is_ghost_post": …,
      "ghost_expires_at": …,
      "is_markup": …,
      "hashtags": …,
      "mentions": …,
      "links": …,
      "image_urls": …,
      "video_urls": …,
      "tagged_users": …,
      "media": …,
      "link_preview": …,
      "location": …,
      "quoted_post": …,
      "reposted_post": …,
      "gif": …,
      "music": …,
      "podcast": …,
      "scorecard": …,
      "trend": …,
      "author_badge": …,
      "custom_like": …,
      "platform": …,
      "in_reply_to": …,
      "reposted_by": …,
      "reposted_at": …
    }
  ],
  "next_page_token": …,
  "pagination": { … },
  "count": …,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## 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
