# Mastodon on Onekey

> 27 endpoints for Mastodon (27 stable, 0 beta), 1 to 5 credits each. Category: Social networks. One key, one JSON shape.

Base URL: https://api.onekey.dev
Auth: header `x-api-key: <key>`. Call shape: `GET /v1/{platform}/{endpoint}?{params}`.
Every response is `{success, data, metadata, error}`; check `success` first. Cost is in `metadata.credits_charged`. Free when served from cache (0.2 credit for a cached response over 100 KB). Failed and not-found calls are refunded.
Status: stable = verified against the live source; beta = not yet verified, fields may be missing.

Page: https://onekey.dev/platforms/mastodon
Reference (Markdown): https://onekey.dev/docs/api/mastodon.md
All docs: https://onekey.dev/llms.txt

## Canonical fields returned

Unified-schema fields (same names on every platform), with how many of the 27 mapped Mastodon endpoints return each:

- `content.text` (string): 19
- `engagement.comments` (integer): 19
- `content.createdAt` (ISO 8601 date): 18
- `author.avatarUrl` (URL): 17
- `author.displayName` (string): 17
- `author.id` (string): 17
- `author.url` (URL): 17
- `author.username` (string): 17
- `content.id` (string): 11
- `content.language` (string): 10
- `content.url` (URL): 10
- `engagement.likes` (integer): 10
- `engagement.shares` (integer): 10
- `author.followers` (integer): 8
- `author.following` (integer): 8
- `entity.name` (string): 8
- `entity.url` (URL): 4
- `content.title` (string): 2
- `media.thumbnailUrl` (URL): 2
- `engagement.views` (integer): 1
- `entity.description` (string): 1
- `media.url` (URL): 1
- `package.version` (string): 1
- plus 7 platform-specific fields under `ext.`

## Endpoints

### mastodon.account_by_id

Fetch a Mastodon account by numeric id (instance-local id).
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/mastodon/account_by_id?id=1` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `id` (string, required): Account id on the instance
- Fields returned: `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `content.text`, `author.followers`, `author.following`, `engagement.comments`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/mastodon/account_by_id.md

### mastodon.custom_emojis

Custom emojis of an instance.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/custom_emojis` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
- Fields returned: `entity.name`, `media.url`, `entity.description`
- Reference: https://onekey.dev/docs/api/mastodon/custom_emojis.md

### mastodon.directory

Profile directory of an instance.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/directory` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
- Fields returned: `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `content.text`, `author.followers`, `author.following`, `engagement.comments`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/mastodon/directory.md

### mastodon.featured_tags

Hashtags featured on a Mastodon profile.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/featured_tags?id=1` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `id` (string, required): Account id on the instance
- Fields returned: `content.id`, `entity.name`, `entity.url`, `content.createdAt`, `ext.statuses`
- Reference: https://onekey.dev/docs/api/mastodon/featured_tags.md

### mastodon.followers

Followers of a Mastodon account.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/followers?id=1` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `id` (string, required): Account id on the instance
- Fields returned: `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `content.text`, `author.followers`, `author.following`, `engagement.comments`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/mastodon/followers.md

### mastodon.following

Accounts a Mastodon account follows.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/following?id=1` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `id` (string, required): Account id on the instance
- Fields returned: `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `content.text`, `author.followers`, `author.following`, `engagement.comments`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/mastodon/following.md

### mastodon.hashtag

Hashtag info and 7-day usage on an instance.
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/mastodon/hashtag?tag=python` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `tag` (string, required): Hashtag without #, e.g. python
- Fields returned: `entity.name`, `entity.url`, `ext.usesToday`, `ext.accountsToday`, `ext.usesYesterday`
- Reference: https://onekey.dev/docs/api/mastodon/hashtag.md

### mastodon.instance

Instance information (v2).
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/mastodon/instance` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
- Fields returned: `entity.name`, `content.title`, `content.text`, `package.version`, `content.language`, `media.thumbnailUrl`, `ext.activeMonth`, `ext.contact`, `ext.registrationsOpen`
- Reference: https://onekey.dev/docs/api/mastodon/instance.md

### mastodon.instance_activity

Weekly activity of an instance.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/instance_activity` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
- Fields returned: `content.createdAt`, `engagement.comments`, `engagement.views`, `engagement.likes`
- Reference: https://onekey.dev/docs/api/mastodon/instance_activity.md

### mastodon.instance_peers

Domains an instance federates with (large list).
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/instance_peers` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default sigmoid.social
- Fields returned: `entity.name`
- Reference: https://onekey.dev/docs/api/mastodon/instance_peers.md

### mastodon.instance_rules

Rules of an instance.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/instance_rules` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
- Fields returned: `content.id`, `content.text`
- Reference: https://onekey.dev/docs/api/mastodon/instance_rules.md

### mastodon.profile

Fetch a Mastodon account (default instance mastodon.social).
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/mastodon/profile?handle=Gargron` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `handle` (string, required): Account name on the instance, e.g. Gargron
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
- Fields returned: `author.id`, `author.username`, `author.displayName`, `author.followers`, `author.following`, `engagement.comments`, `author.url`, `author.avatarUrl`
- Reference: https://onekey.dev/docs/api/mastodon/profile.md

### mastodon.search_accounts

Search Mastodon accounts.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/search_accounts?q=python` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `q` (string, required): Search query
- Fields returned: `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `content.text`, `author.followers`, `author.following`, `engagement.comments`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/mastodon/search_accounts.md

### mastodon.search_hashtags

Search Mastodon hashtags.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/search_hashtags?q=python` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `q` (string, required): Search query
- Fields returned: `entity.name`, `entity.url`, `ext.usesToday`, `ext.accountsToday`
- Reference: https://onekey.dev/docs/api/mastodon/search_hashtags.md

### mastodon.status

A single Mastodon post by instance-local id.
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/mastodon/status?id=117347462442266995` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `id` (string, required): Status id on the instance
- Fields returned: `content.id`, `content.url`, `content.text`, `content.createdAt`, `content.language`, `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `engagement.likes`, `engagement.comments`, `engagement.shares`
- Reference: https://onekey.dev/docs/api/mastodon/status.md

### mastodon.status_context_replies

Replies to a Mastodon post.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/status_context_replies?id=117347462442266995` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `id` (string, required): Status id on the instance
- Fields returned: `content.id`, `content.url`, `content.text`, `content.createdAt`, `content.language`, `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `engagement.likes`, `engagement.comments`, `engagement.shares`
- Reference: https://onekey.dev/docs/api/mastodon/status_context_replies.md

### mastodon.status_favourited_by

Accounts that favourited a Mastodon post.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/status_favourited_by?id=117347462442266995` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `id` (string, required): Status id on the instance
- Fields returned: `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `content.text`, `author.followers`, `author.following`, `engagement.comments`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/mastodon/status_favourited_by.md

### mastodon.status_reblogged_by

Accounts that boosted a Mastodon post.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/status_reblogged_by?id=117347462442266995` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `id` (string, required): Status id on the instance
- Fields returned: `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `content.text`, `author.followers`, `author.following`, `engagement.comments`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/mastodon/status_reblogged_by.md

### mastodon.statuses

Recent public posts by a Mastodon account (by instance-local account id).
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/statuses?id=1` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `id` (string, required): Account id on the instance
- Fields returned: `content.id`, `content.url`, `content.text`, `content.createdAt`, `content.language`, `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `engagement.likes`, `engagement.comments`, `engagement.shares`
- Reference: https://onekey.dev/docs/api/mastodon/statuses.md

### mastodon.statuses_media

Media posts by a Mastodon account.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/statuses_media?id=1` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `id` (string, required): Account id on the instance
- Fields returned: `content.id`, `content.url`, `content.text`, `content.createdAt`, `content.language`, `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `engagement.likes`, `engagement.comments`, `engagement.shares`
- Reference: https://onekey.dev/docs/api/mastodon/statuses_media.md

### mastodon.statuses_pinned

Pinned posts of a Mastodon account.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/statuses_pinned?id=1` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `id` (string, required): Account id on the instance
- Fields returned: `content.id`, `content.url`, `content.text`, `content.createdAt`, `content.language`, `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `engagement.likes`, `engagement.comments`, `engagement.shares`
- Reference: https://onekey.dev/docs/api/mastodon/statuses_pinned.md

### mastodon.timeline_local

Local timeline of an instance (anonymous access).
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/timeline_local` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default fosstodon.org
- Fields returned: `content.id`, `content.url`, `content.text`, `content.createdAt`, `content.language`, `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `engagement.likes`, `engagement.comments`, `engagement.shares`
- Reference: https://onekey.dev/docs/api/mastodon/timeline_local.md

### mastodon.timeline_public

Federated public timeline (instances that allow anonymous access).
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/timeline_public` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default fosstodon.org
- Fields returned: `content.id`, `content.url`, `content.text`, `content.createdAt`, `content.language`, `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `engagement.likes`, `engagement.comments`, `engagement.shares`
- Reference: https://onekey.dev/docs/api/mastodon/timeline_public.md

### mastodon.timeline_tag

Public posts for a hashtag.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/timeline_tag?tag=python` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
  - `tag` (string, required): Hashtag without #, e.g. python
- Fields returned: `content.id`, `content.url`, `content.text`, `content.createdAt`, `content.language`, `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `engagement.likes`, `engagement.comments`, `engagement.shares`
- Reference: https://onekey.dev/docs/api/mastodon/timeline_tag.md

### mastodon.trends_links

Trending links on an instance.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/trends_links` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
- Fields returned: `content.url`, `content.title`, `content.text`, `entity.name`, `media.thumbnailUrl`, `engagement.shares`, `engagement.comments`
- Reference: https://onekey.dev/docs/api/mastodon/trends_links.md

### mastodon.trends_statuses

Trending posts on an instance.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/trends_statuses` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
- Fields returned: `content.id`, `content.url`, `content.text`, `content.createdAt`, `content.language`, `author.id`, `author.username`, `author.displayName`, `author.url`, `author.avatarUrl`, `engagement.likes`, `engagement.comments`, `engagement.shares`
- Reference: https://onekey.dev/docs/api/mastodon/trends_statuses.md

### mastodon.trends_tags

Trending hashtags on an instance.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/mastodon/trends_tags` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `instance` (string, optional): Known Mastodon instance (allowlisted), default mastodon.social
- Fields returned: `entity.name`, `entity.url`, `ext.usesToday`, `ext.accountsToday`
- Reference: https://onekey.dev/docs/api/mastodon/trends_tags.md

## Sample request

```bash
curl "https://api.onekey.dev/v1/mastodon/account_by_id?id=1" \
  -H "x-api-key: YOUR_API_KEY"
```