# Mastodon 热榜 API (mastodon.trending)

- Canonical page: [https://everyinfra.com/mastodon-api/trending](https://everyinfra.com/mastodon-api/trending?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "mastodon", "action": "trending", "params": {...}}
- Price: $0.001389 per call ($1.39 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 20, max 100 per call
- Mode: sync; add "mode": "async" for slow tasks

热榜读取一个 Mastodon 实例上的热门内容，默认 20 条、单次最多 100 条。每条都是完整的帖子记录，带 `is_reblog`，能看出上榜的是原帖还是转嘟。它回答「这个实例上什么内容受关注」，适合找选题、观察社区关心的话题，或者给一份周报挑代表性的帖子。

没有必填参数，`instance` 不传时读 mastodon.social，填域名即可换实例，不带协议或路径。换几个实例各调一次，就能比较不同社区里的热点有什么不同。

## Health

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

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| instance | not declared | no | not declared | Mastodon 实例域名，不带协议或路径。timeline 默认 fosstodon.org，其他入口默认 mastodon.social；显式 instance 优先于 username 中的实例，因此二者应保持一致。 |
| limit | integer (1–100) | no | 20 | 这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | 该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。 |
| url | 该记录在原平台上的可访问链接。 |
| text | 正文内容，已去除 HTML 标签，全文返回、不截断（个别平台的列表结果本身只有摘要，以该平台的字段说明为准）。 |
| author_name | 作者昵称（显示名）。 |
| author_username | 作者用户名（@handle），通常可用于拼 URL。 |
| author_url | 作者在原平台的主页链接。 |
| instance | 所属实例域名。 |
| like_count | 点赞数。null 表示该平台或该接口不公开此数据，不等于 0。 |
| reblog_count | 转嘟数。 |
| comment_count | 评论数。null 表示不公开，不等于 0。 |
| language | 内容语言代码（如 zh、en），由平台判定，可能不准。 |
| is_reblog | 是否为转嘟（Mastodon 的转发）。 |
| posted_at | 发布时间，ISO 8601 格式、UTC 时区（如 2026-08-07T12:34:56+00:00）。平台只给非标准字符串时原样透传，解析前建议做容错。null 表示平台未公开。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |
| media_urls | platform-native meaning |
| hashtags | 正文里的话题标签数组，按出现顺序；没有时不出现这个字段。 |

## 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": "mastodon",
  "action": "trending",
  "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": "mastodon",
        "action": "trending",
        "params": {},
    },
    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 20. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "mastodon",
  "action": "trending",
  "results": [
    {
      "id": "•••",
      "url": "https://fosstodon.org/@•••/117335498435037854",
      "text": "Trailer of Musk, the documentary, scheduled for released theatrically in the U.S. on October 9.\n\nLet's share it far and wide.\n\nhttps://www.youtube.com/watch?v=eY_8SyndC10\nhttps://en.wikipedia.org/wiki/Musk_(film)\n1/n",
      "author_name": "•••",
      "author_username": "•••",
      "instance": "fosstodon.org",
      "like_count": 132,
      "reblog_count": 254,
      "comment_count": 6,
      "language": "en",
      "posted_at": "2026-09-26T04:40:20+00:00",
      "platform": "mastodon"
    },
    {
      "id": "•••",
      "url": "https://social.openrightsgroup.org/@•••/117336385496326440",
      "text": "We’ve been put on a watchlist 🚨\n\n“It is deeply concerning to see the Prevent duty being used to enable the monitoring of people and organisations simply because they are critical of the programme.\n\nThat raises serious questions about freedom of expression and the right to dissent…",
      "author_name": "•••",
      "author_username": "•••",
      "instance": "social.openrightsgroup.org",
      "like_count": 27,
      "reblog_count": 79,
      "comment_count": 5,
      "language": "en",
      "posted_at": "2026-09-26T08:25:55+00:00",
      "platform": "mastodon",
      "hashtags": [
        "prevent",
        "surveillance",
        "ukpolitics"
      ]
    }
  ],
  "count": 20,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### 热榜里的帖子是怎么排的？

接口没有说明排序规则。要比较热度，就看每条自带的 `like_count`、`reblog_count` 和 `comment_count`，自己排序；其中为 null 的是不公开，不能当 0 排。

### 热榜和话题内容有什么不同？

热榜不需要任何内容参数，只靠 `instance` 决定读哪里，给的是这个实例上受关注的内容。话题内容要传标签词，只读一个标签下的帖子，而且不含转嘟和回复。先看热榜找方向，再用话题内容盯住具体的标签。

### 热榜适合做定期监测吗？

适合做定点观察：固定 `instance`，按固定间隔读取，把 `id` 存下来，对比两次的名单就能看出新上榜的内容。`posted_at` 是 UTC 时间，按天统计前先换成本地时区。

## Also

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