POST

API health

24h health
Normal
  • Healthy / normal
  • Available
  • Limited
  • Mostly down
Normal

Last 24 hours

Last 30 days

Resolve a Mastodon handle or user@instance address to one account's display name, full handle, home instance and profile link. A bare handle is looked up on mastodon.social unless instance is set, and a match does not prove it is the account you meant.

Send POST https://api.everyinfra.com/api/v1/social with platform set to mastodon and action set to profile. Price $1.39 per 1,000 requests ($0.001389 per call). Failed calls and empty results are not charged. Synchronous. For slow jobs add "mode": "async" to the body, take the job_id and poll.

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.

AI prompt

#
Please help me write a data collection script with the EveryInfra Mastodon Details endpoint (mastodon/profile).

How the endpoint works:
- Request: POST https://api.everyinfra.com/api/v1/social with the header Authorization: Bearer <API key>. Read the key from the EVERYINFRA_API_KEY environment variable and never hard-code it.
- In the request body, set platform to mastodon and action to profile, and put the parameters inside params.
- Required parameters:
  - username: Specifies the Mastodon account handle or full user@instance format, with an optional leading @ symbol.
- Optional parameters:
  - instance: Selects a Mastodon instance domain without a scheme or path. Timeline defaults to fosstodon.org and other actions default to mastodon.social.
- Returns one object. Main fields: username, display_name, handle, instance, url.
- Example request body:
{
  "platform": "mastodon",
  "action": "profile",
  "params": {
    "username": "Mastodon@mastodon.social"
  }
}
- Price: $1.39 per 1,000 requests; failed and empty results are not charged.
- For dozens or hundreds of targets, add "mode": "async" to the body: you get a job_id at once and poll GET https://api.everyinfra.com/api/v1/jobs/{job_id} for the result.
- On 422, fix the request using the suggested parameter names and allowed values in the error; on 429 or 503, wait for Retry-After and try again.

Before writing code, ask me which targets I need, how many, which fields, and what output format I want; then confirm the plan and the rough cost with me.

Request parameters

#
NameInTypeRequiredDefaultDescription
AuthorizationheaderstringYes-Bearer followed by your API key. Create it in the console; never put it in a URL or a code repository.
platformbodystringYesmastodonPlatform identifier, fixed value.
actionbodystringYesprofileCapability identifier, fixed value.
usernamebody.paramsstringYes-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.
instancebody.paramsstringNo-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.

Code samples

#
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"
  }
}'

OpenAPI definition (JSON)Samples read the key from the EVERYINFRA_API_KEY environment variable; copied code never contains your key.

Response example

#
Captured September 26, 2026 at 08:56 (UTC) by calling this API with the parameters in the code sample above. results and count are that call's real response 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.
json
{  "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": { … }}

Response fields

#

Business data is in results. The table lists the fields a record can contain; values the platform does not show are never made up.

FieldMeaning
usernameUsername (@handle).
display_nameDisplay name; can differ from username.
handleKeeps the platform's own meaning
instanceKeeps the platform's own meaning
urlLink to the record on the platform.
platformSource platform identifier, the same as platform in the request (for example xiaohongshu, tiktok).

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.

Errors and billing

#
401
Missing or invalid key.
402
Insufficient balance. Top up first.
422
Invalid parameter name or value. Fix it using the suggestions in the error. No charge.
429
Per-minute request limit reached. Wait for Retry-After, then try again.
503
Could not complete. The held charge is returned to your balance. If the outcome is unknown, verify it before you retry.
200 empty
No data. No charge.

Errors

Official references

#

Used only to check objects and terms. They do not imply authorization or endorsement of EveryInfra by the platform.

  • Mastodon WebFinger: Account Handles Require Domain Resolution ↗

    Official documentation explicitly states that @user@example.com and @user@example.org are distinct accounts, defined by both username and domain. This document clarifies account identification rules and does not imply that this gateway returns all official Account metadata.

    Checked 2026-09-04

Google Analytics needs consent. Privacy