# Mastodon Details API (mastodon.profile)

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

Mastodon Details looks up one Mastodon account and returns who it is: `username`, display name, the full `handle` in the form @user@instance, the `instance` that hosts it, and the profile link. Researchers and community teams use it to resolve a name seen in a post or a list to one exact account, to normalize the accounts in a dataset to a single identifier, or to confirm which server an account lives on before reading its posts.

Mastodon is federated, so the same username can belong to different people on different servers, and only `handle` is unique across the network; store it as the key. Pass the account as user@instance, with or without the leading @. A bare username without `instance` is looked up on mastodon.social, and when you set `instance` it overrides any server written in `username`, so keep the two consistent.

## Health

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

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

## Response fields (items in `results`)

| field | meaning |
|---|---|
| username | Username (@handle). |
| display_name | Display name; can differ from username. |
| handle | platform-native meaning |
| instance | platform-native meaning |
| url | Link to the record on the platform. |
| platform | Source platform identifier, the same as platform in the request (for example xiaohongshu, tiktok). |

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

```text
{
  "id": "req_…",
  "platform": "mastodon",
  "action": "profile",
  "results": {
    "username": "•••",
    "display_name": "•••",
    "handle": "@Mastodon@mastodon.social",
    "instance": "mastodon.social",
    "url": "https://mastodon.social/@•••",
    "platform": "mastodon"
  },
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### Why can the same username belong to different people?

Each Mastodon server has its own users, so alice on mastodon.social and alice on fosstodon.org are separate accounts. Send the full user@instance form, then check `handle` in the result: it is the only identifier that is unique across the whole network.

### What happens if `username` and `instance` disagree?

The explicit `instance` wins over the server written in `username`, so a request for alice@mastodon.social with `instance` set to another domain is looked up on that other server. Leave `instance` out when `username` already names the server, or make the two match, and write it as a bare domain without https:// or a path.

### How do I read this account's posts?

Pass the same user@instance value to the Mastodon Posts by user capability, which follows the same `username` and `instance` rules. If you started from a short username, the `instance` returned here tells you which server to name.

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