# Mastodon Account Scraper (`xtracto/mastodon-account-scraper`) Actor

Get Mastodon account metadata from any instance.

- **URL**: https://apify.com/xtracto/mastodon-account-scraper.md
- **Developed by:** [Farhan Febrian Nauval](https://apify.com/xtracto) (community)
- **Categories:** Social media, Lead generation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Mastodon Account Scraper

Extract public profile data from any Mastodon account across the Fediverse — display name, bio, follower and following counts, status count, profile photo, header image, creation date, bot flag, and locked status — in a clean structured JSON output.

### Why use this actor

- **Works across any instance** — `mastodon.social`, `mas.to`, `fosstodon.org`, `infosec.exchange`, `hachyderm.io`, and every other Mastodon (or ActivityPub-compatible) server, all from the same actor.
- **No account / no login required** — just give it a `user@instance.tld` handle.
- **Full bio with HTML preserved** — links, mentions, and custom emoji markup are kept intact in the `note` field so you can render or parse them downstream.
- **Bot detection built in** — every record exposes the `bot` flag exactly as the account owner set it, plus `locked` (private follow approval) and `discoverable` (opted into directory listings).
- **Verified profile fields** — the four custom fields with their `verified_at` timestamps come through unchanged, so you can trust the "verified link" badge.
- **Stable JSON output** suitable for pipelines, spreadsheets, and databases — every row carries `_input`, `_instance`, `_source`, `_scrapedAt` envelope fields so you can join results back to your input list.

### How it works

1. You provide a list of Mastodon handles in `user@instance.tld` format (e.g. `Gargron@mastodon.social`).
2. The actor talks to each account's home instance and reads the public profile record the same way the Mastodon web app does, then assembles a flat JSON record.
3. Results stream into your dataset, ready to download as JSON, CSV, or Excel.

You do not need to manage scrapers, instance discovery, or rotating IPs — all handled internally.

### Input

```json
{
  "accounts": [
    "Gargron@mastodon.social",
    "atomicpoet@mas.to"
  ],
  "instance": "mastodon.social",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["DATACENTER"]
  }
}
```

| Field | Type | Description |
|---|---|---|
| `accounts` | array | List of Mastodon handles in `user@instance.tld` form. The instance suffix is what tells the actor where to look — `Gargron@mastodon.social` and `Gargron@mas.to` are two different accounts. Full profile URLs (e.g. `https://mastodon.social/@Gargron`) are also accepted. |
| `instance` | string | Default instance used only when an entry in `accounts` is a bare username with no `@instance` suffix. Defaults to `mastodon.social`. |
| `accessToken` | string | Optional Mastodon API token. Most instances do not need one — provide it only for private or invite-only instances that block anonymous lookups. |
| `proxyConfiguration` | object | Apify Proxy settings. Datacenter proxy works for most cases. |

### Output

Input: `Gargron@mastodon.social`

```json
{
  "_input": "Gargron@mastodon.social",
  "_instance": "mastodon.social",
  "_source": "S1-api",
  "_scrapedAt": "2026-05-18T11:13:17.515158+00:00",
  "id": "1",
  "username": "Gargron",
  "acct": "Gargron",
  "display_name": "Eugen Rochko",
  "locked": false,
  "bot": false,
  "discoverable": true,
  "indexable": true,
  "group": false,
  "created_at": "2016-03-16T00:00:00.000Z",
  "note": "<p>Executive Strategy &amp; Product Advisor, Founder of <span class=\"h-card\">@<span>Mastodon</span></span>. Film photography, prog metal, Dota 2. Likes all things analog.</p>",
  "url": "https://mastodon.social/@Gargron",
  "uri": "https://mastodon.social/users/Gargron",
  "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/a0a49d80c3de5f75.png",
  "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/a0a49d80c3de5f75.png",
  "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/d13e4417706a5fec.jpg",
  "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/d13e4417706a5fec.jpg",
  "followers_count": 380126,
  "following_count": 711,
  "statuses_count": 81382,
  "last_status_at": "2026-05-17",
  "noindex": false,
  "emojis": [],
  "roles": [],
  "fields": [
    { "name": "GitHub", "value": "https://github.com/Gargron", "verified_at": "2023-02-07T23:24:40.347+00:00" },
    { "name": "Portfolio", "value": "https://eugenrochko.com", "verified_at": "2024-07-06T01:06:10.801+00:00" },
    { "name": "Mastodon Merch", "value": "https://shop.joinmastodon.org", "verified_at": null }
  ]
}
```

| Field | Type | Description |
|---|---|---|
| `_input` | string | The handle exactly as you supplied it. Use this to join results back to your input list. |
| `_instance` | string | The Mastodon instance the record was fetched from (e.g. `mastodon.social`). Useful for grouping or filtering by server. |
| `_source` | string | Internal tag for the path used to fetch the record. `S1-api` is the standard public lookup path. |
| `_scrapedAt` | string | ISO-8601 UTC timestamp when the record was scraped. |
| `id` | string | Mastodon's internal numeric account ID on the home instance. Stable across username changes. |
| `username` | string | Local username on the home instance (e.g. `Gargron`). |
| `acct` | string | Account identifier — bare username when the account is local to the instance you queried, or `user@instance.tld` when remote. |
| `display_name` | string | Display name set by the user (free-form text, may contain custom emoji shortcodes). |
| `locked` | boolean | `true` if the account requires manual approval for new followers. |
| `bot` | boolean | `true` if the account owner has flagged this as an automated / bot account. |
| `discoverable` | boolean | `true` if the user opted into appearing in the profile directory and recommendations. |
| `indexable` | boolean | `true` if the user allows search engines to index their statuses. |
| `group` | boolean | `true` if the account is a Mastodon group account rather than a person. |
| `created_at` | string | ISO-8601 timestamp of when the account was created on its home instance. |
| `note` | string | The bio / about section, with HTML markup preserved (links, mentions, line breaks). |
| `url` | string | Canonical public profile URL on the home instance. |
| `uri` | string | ActivityPub actor URI — the federated identifier used for cross-instance communication. |
| `avatar` | string | URL of the profile picture (animated if the user uploaded a GIF). |
| `avatar_static` | string | URL of the still-frame profile picture. |
| `header` | string | URL of the profile header banner image. |
| `header_static` | string | URL of the still-frame header banner. |
| `followers_count` | integer | Number of accounts following this profile. |
| `following_count` | integer | Number of accounts this profile follows. |
| `statuses_count` | integer | Total number of public statuses (posts) the account has published. |
| `last_status_at` | string | Date of the most recent public status (YYYY-MM-DD). `null` if the account has never posted. |
| `noindex` | boolean | `true` if the user opted out of search-engine indexing. |
| `emojis` | array | Custom emoji used in the display name or bio (each item has `shortcode`, `url`, `static_url`). |
| `roles` | array | Public roles assigned by the home instance (e.g. moderator badge). Empty for normal users. |
| `fields` | array | Up to four custom profile fields. Each item has `name`, `value` (with HTML), and `verified_at` — non-null when the link was verified via `rel="me"`. |

#### Error envelope

Accounts that don't exist, are on an unreachable instance, or are suspended return a structured error instead of crashing the run:

```json
{
  "_input": "this-user-does-not-exist@mastodon.social",
  "_instance": "mastodon.social",
  "_user": "this-user-does-not-exist",
  "_error": "not_found",
  "_errorDetail": "NotFound: account lookup returned 404",
  "_source": "S1-api",
  "_scrapedAt": "2026-05-18T11:13:18.012345+00:00"
}
```

Common `_error` values: `not_found` (suspended, deleted, or never existed), `invalid_input` (couldn't parse the handle — usually a missing `@instance` suffix on a bare username with no default set), `fetch_failed` (instance unreachable or returned a transient error).

Filter on `_error` to triage failed rows.

### Pricing

This actor is billed per result: **$1.50 per 1,000 profiles**. Each successful profile = 1 result. Errors (not-found, suspended, invalid input) are not billed.

### Other Sosmed Actors

| Platform | Actor | Best for |
|---|---|---|
| Mastodon | [Mastodon Status Detail Scraper](https://apify.com/xtracto/mastodon-status-detail-scraper) | Full post content, boosts, replies, media |
| Bluesky | [Bluesky Account Scraper](https://apify.com/xtracto/bluesky-account-scraper) | atproto profile + counters |
| Threads | [Threads Account Scraper](https://apify.com/xtracto/threads-account-scraper) | Profile data for a Threads handle |
| Twitter / X | [X Account Scraper](https://apify.com/xtracto/x-account-scraper) | Profile + tweet counts for any handle |
| Tumblr | [Tumblr Blog Scraper](https://apify.com/xtracto/tumblr-blog-scraper) | Blog title, description, post count |
| Reddit | [Reddit User Profile Scraper](https://apify.com/xtracto/reddit-user-profile-scraper) | Karma, posts, trophies |

Browse the full catalog at [apify.com/xtracto](https://apify.com/xtracto).

### Notes

- **Mastodon is decentralized — the instance matters.** `alice@mastodon.social` and `alice@mas.to` are two different accounts on two different servers. Always include the `@instance.tld` suffix in your input (or set the `instance` field for bare usernames).
- **Rate limits are per-instance.** Each Mastodon server enforces its own limits — typically 300 unauthenticated requests per 5 minutes per IP. For large bulk runs against a single instance, enable Apify Proxy rotation.
- **Pleroma, Akkoma, GoToSocial, and other forks** are mostly compatible. Profile shape may vary slightly (extra fields, missing flags); the core username / display_name / follower counts / bio are always present.
- **Counters are eventually-consistent** and may lag the live network by a few minutes due to federation delays.
- **Private / invite-only instances** that have set `DISALLOW_UNAUTHENTICATED_API_ACCESS` will reject anonymous lookups. Provide an `accessToken` from that instance to unlock them.
- **Suspended, deleted, or never-existed accounts** return `{"_error": "not_found", "_input": "..."}`.

# Actor input Schema

## `accounts` (type: `array`):

List of Mastodon handles in the form 'user@instance.tld' (for example 'Gargron@mastodon.social'). Bare usernames are accepted when you also set the 'instance' field below. Full profile URLs (https://mastodon.social/@Gargron) are also accepted.

## `instance` (type: `string`):

Default Mastodon instance to use when an entry in 'accounts' is a bare username with no '@instance' suffix. Leave as 'mastodon.social' if you are not sure.

## `accessToken` (type: `string`):

Optional Mastodon API token. Most instances do not need one, but some private or invite-only instances require an access token to view public profiles. You can create a token under Preferences > Development on the instance you want to query.

## `proxyConfiguration` (type: `object`):

Apify Proxy settings. Datacenter proxy works for most Mastodon instances. Switch to residential proxy if you scrape large volumes from a single instance.

## Actor input object example

```json
{
  "accounts": [
    "Gargron@mastodon.social",
    "atomicpoet@mas.to"
  ],
  "instance": "mastodon.social",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `id` (type: `string`):

Unique identifier of the item at the source.

## `username` (type: `string`):

Account username.

## `acct` (type: `string`):

Acct as reported by the source.

## `display_name` (type: `string`):

Display name as reported by the source.

## `locked` (type: `string`):

Locked as reported by the source.

## `bot` (type: `string`):

Bot as reported by the source.

## `discoverable` (type: `string`):

Discoverable as reported by the source.

## `indexable` (type: `string`):

Indexable as reported by the source.

## `group` (type: `string`):

Group as reported by the source.

## `created_at` (type: `string`):

Created at as reported by the source.

## `note` (type: `string`):

Free-text note from the source.

## `url` (type: `string`):

Direct link to the scraped item.

## `uri` (type: `string`):

Resource identifier at the source.

## `avatar` (type: `string`):

Profile picture URL.

## `avatar_static` (type: `string`):

Avatar static as reported by the source.

## `header` (type: `string`):

Header as reported by the source.

## `header_static` (type: `string`):

Header static as reported by the source.

## `followers_count` (type: `string`):

Followers count. Whole number.

## `following_count` (type: `string`):

Following count. Whole number.

## `statuses_count` (type: `string`):

Statuses count. Whole number.

## `last_status_at` (type: `string`):

Last status at as reported by the source.

## `noindex` (type: `string`):

Noindex as reported by the source.

## `emojis` (type: `string`):

Emojis.

## `roles` (type: `string`):

Roles.

## `fields` (type: `string`):

Fields.

## `_input` (type: `string`):

The input value this row was produced from.

## `_instance` (type: `string`):

Instance as reported by the source.

## `_source` (type: `string`):

Which extraction strategy produced the row.

## `_scrapedAt` (type: `string`):

UTC timestamp of the scrape, ISO 8601.

## `_user` (type: `string`):

User as reported by the source.

## `_error` (type: `string`):

Set only on diagnostic rows - why that target produced no data.

## `_errorDetail` (type: `string`):

Extra context for the error.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "accounts": [
        "Gargron@mastodon.social",
        "atomicpoet@mas.to"
    ],
    "instance": "mastodon.social"
};

// Run the Actor and wait for it to finish
const run = await client.actor("xtracto/mastodon-account-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "accounts": [
        "Gargron@mastodon.social",
        "atomicpoet@mas.to",
    ],
    "instance": "mastodon.social",
}

# Run the Actor and wait for it to finish
run = client.actor("xtracto/mastodon-account-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "accounts": [
    "Gargron@mastodon.social",
    "atomicpoet@mas.to"
  ],
  "instance": "mastodon.social"
}' |
apify call xtracto/mastodon-account-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,xtracto/mastodon-account-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/QtRGGaerGaDM75Md2/builds/ptv2KbNjFOWq8AI4R/openapi.json
