# Mastodon Trending API (mastodon.trending)

- Canonical page: [https://everyinfra.com/en/mastodon-api/trending](https://everyinfra.com/en/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

## 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 | Selects a Mastodon instance domain without a scheme or path. Timeline defaults to fosstodon.org and other actions default to mastodon.social. An explicit instance takes precedence over the domain in username, so keep the two values consistent. |
| limit | integer (1–100) | no | 20 | The most rows to return in this call, an integer from 1 to 100. The default applies when you leave it out, and a call can return fewer rows. Larger values return 422 before any charge. |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | The record's unique ID on the platform. Unique only within one platform; IDs can repeat across platforms. |
| url | Link to the record on the platform. |
| text | Body text with HTML removed, returned in full and never cut short (on a few platforms the list results themselves carry only an excerpt; the platform's field notes say so). |
| author_name | Author's display name. |
| author_username | Author's username (@handle), usually usable in URLs. |
| author_url | Link to the author's profile on the platform. |
| instance | platform-native meaning |
| like_count | Likes. null means the platform or this capability does not disclose it; it is not 0. |
| reblog_count | platform-native meaning |
| comment_count | Comments. null means not disclosed, not 0. |
| language | Content language code (for example zh, en) as judged by the platform; it can be wrong. |
| is_reblog | platform-native meaning |
| posted_at | Publish time in ISO 8601, UTC (for example 2026-08-07T12:34:56+00:00). Non-standard strings from the platform are passed through as is, so parse defensively. null means the platform does not disclose it. |
| platform | Source platform identifier, the same as platform in the request (for example xiaohongshu, tiktok). |
| media_urls | platform-native meaning |
| hashtags | Hashtags in the text, in order of appearance; absent when there are none. |

## 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": { … }
}
```

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