# Mastodon Posts by user API (mastodon.user_posts)

- Canonical page: [https://everyinfra.com/en/mastodon-api/user_posts](https://everyinfra.com/en/mastodon-api/user_posts?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "mastodon", "action": "user_posts", "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 Posts by user follows one account on a Mastodon server, named in `username` as user@instance, and returns its public posts. Each row carries the post text with HTML removed, its link, like, boost and reply counts, the language, whether the row is a boost, the publish time, the hosting `instance`, and the author's name, handle and profile link. Journalists, open-source maintainers and researchers use it to follow what an account publishes on the fediverse: tracking institutions and projects that post on Mastodon, studying which posts get boosted, or building a dataset for language research.

Write the server into the value, as in Mastodon@mastodon.social: without a server in `username` or `instance`, a bare name is looked up on mastodon.social and may reach a different person than you meant. `reblog_count` counts boosts of a post and `comment_count` counts replies, and a null `like_count` or `comment_count` means the number was not disclosed rather than zero.

## Health

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

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| username | not declared | yes | not declared | Specifies the Mastodon account handle or full user@instance format, with an optional leading @ symbol. Providing a short handle without specifying an instance defaults to mastodon.social, and identical usernames across different instances represent distinct accounts. |
| 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": "user_posts",
  "params": {
    "username": "<USERNAME>@mastodon.social"
  }
}'
```

```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": "user_posts",
        "params": {
            "username": "<USERNAME>@mastodon.social",
        },
    },
    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": "mastodon",
  "action": "user_posts",
  "results": [
    {
      "id": …,
      "url": …,
      "text": …,
      "author_name": …,
      "author_username": …,
      "author_url": …,
      "instance": …,
      "like_count": …,
      "reblog_count": …,
      "comment_count": …,
      "language": …,
      "is_reblog": …,
      "posted_at": …,
      "platform": …,
      "media_urls": …,
      "hashtags": …
    }
  ],
  "count": …,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### What is a reblog?

A reblog, also called a boost, is Mastodon's repost: an account sharing someone else's post with its own followers. Rows where `is_reblog` is true are boosts rather than the account's own writing, so drop them when you analyze what it says; `reblog_count` on a post is how often others boosted it.

### Can I filter posts by `language`?

Yes, after the call. `language` is a code such as en or de that the platform assigns to each post, and that judgment can be wrong. Spot-check a sample against `text` before you drop rows by language, or run your own detection when precision matters.

### How do I get the account's profile details?

Use the Mastodon Details capability with the same `username` and `instance`. It returns the display name, the full handle in @user@instance form and the hosting server; the handle is unique across the fediverse, so it is a sound key for joining posts to accounts.

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