# Mastodon Scraper - Posts, Hashtags, Accounts & Trends (`navy_currant/mastodon-social-scraper`) Actor

Scrape Mastodon (any instance) via the official public REST API: hashtag timelines, account posts + profiles, trending statuses/tags/links, and account/hashtag search. No credentials, no proxy required.

- **URL**: https://apify.com/navy\_currant/mastodon-social-scraper.md
- **Developed by:** [Ishaan](https://apify.com/navy_currant) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Mastodon Scraper — Posts, Hashtags, Accounts & Trends

Scrape **Mastodon** (any instance) using the official **public REST API** — no account, no API key, no proxy spend required. Mastodon is federated, so you can point this actor at `mastodon.social` (default) or any other instance.

### What it does

- **Hashtag timeline** — pull recent public posts for any `#tag`, paginated, with an optional media-only filter
- **Account** — fetch a user's **profile** plus their posts (with reply/reblog filters)
- **Trends** — what's trending **now**: trending statuses, hashtags, or news links
- **Search** — find **accounts** or **hashtags** by keyword
- **Unified output** — statuses, accounts, tags and links in one dataset with consistent field names and both raw-HTML and plain-text bodies, ready for analysis or AI pipelines

### Why use this actor

| Competitor actor | Problem | This actor |
|---|---|---|
| newpo/mastodon-scraper (~122 users) | Single-instance assumptions, subscription pricing | Any instance, **pay-per-result** |
| Generic single-mode scrapers (2–4 users) | Hashtags **or** accounts, not both | Hashtag **+** account **+** trends **+** search in one |
| Roll-your-own API calls | Pagination, HTML stripping, charge logic to maintain | One input, clean schema, plain-text + HTML, pay per result |

The Fediverse is a fast-growing, **open** social network — a natural input for **social listening**, brand monitoring, academic research, and **RAG pipelines** that want public discourse without platform lock-in.

### Output fields

**Statuses** (`type: "status"`): `id`, `url`, `uri`, `created_at`, `edited_at`, `language`, `visibility`, `text` (plain), `content_html`, `spoiler_text`, `sensitive`, `is_reblog`, `in_reply_to_id`, `replies_count`, `reblogs_count`, `favourites_count`, `author_id`, `author_acct`, `author_username`, `author_display_name`, `author_url`, `author_followers`, `tags[]`, `media_count`, `media_urls[]`, `card_url`

**Accounts** (`type: "account"`): `id`, `acct`, `username`, `url`, `display_name`, `note` (plain), `note_html`, `created_at`, `last_status_at`, `bot`, `locked`, `discoverable`, `followers_count`, `following_count`, `statuses_count`, `avatar_url`, `header_url`, `fields[]`

**Tags** (`type: "tag"`): `name`, `url`, `total_uses`, `total_accounts`, `history[]`

**Links** (`type: "link"`): `url`, `title`, `description`, `provider_name`, `author_name`, `published_at`, `image`, `total_uses`, `total_accounts`, `history[]`

### Usage examples

Recent posts for two hashtags:

```json
{
  "mode": "hashtag",
  "instance": "mastodon.social",
  "searchTerms": ["ai", "opensource"],
  "maxResultsPerTerm": 500
}
```

A user's profile + original posts (no replies/boosts):

```json
{
  "mode": "account",
  "instance": "mastodon.social",
  "accounts": ["Gargron"],
  "excludeReplies": true,
  "excludeReblogs": true,
  "maxResultsPerTerm": 200
}
```

What's trending right now:

```json
{ "mode": "trends", "trendType": "statuses", "maxResultsPerTerm": 40 }
```

### Pricing

**Pay per event:** $0.003 per result.

Example: 5,000 items ≈ **$15**.

### Technical notes

- Uses each instance's official Mastodon REST API (`/api/v1/timelines/tag`, `/api/v1/accounts`, `/api/v1/trends/*`, `/api/v2/search`) — free, public, no key
- **Zero proxy cost** — official API, no anti-bot bypass
- Polite rate limiting; `max_id` / `offset` pagination handled for you
- Status/account text is returned both as raw `content_html` and stripped plain `text`
- Automatically stops when the user's spending limit is reached — charge respected per result, no overrun

#### Honest scope / limits

- **Public timeline mode is intentionally absent**: most instances (including mastodon.social) return `422` for the anonymous local/public timeline. Use **hashtag** mode for a topic feed.
- **Search is accounts + hashtags only.** Full-text **status** search requires an authenticated account on a server that has opted in to search — not available keyless. Use **hashtag** mode for posts on a topic.
- **Account mode** resolves handles known to the chosen instance. For a remote user, set `instance` to that user's home server.

### Common use cases

- **Social listening / brand monitoring** — track a hashtag or competitor across the Fediverse
- **RAG pipelines** — feed fresh, open public discourse into retrieval systems
- **Trend monitoring** — daily pulls of trending statuses/tags/links for a dashboard
- **Academic / network research** — collect public posts and account metadata at scale

### Data compliance

This actor accesses only **public** Mastodon data through each instance's official, publicly documented REST API. No login credentials are used. Public posts and profiles are intentionally public; suitable for research and business use. Respect each instance's terms and the authors' content.

# Actor input Schema

## `mode` (type: `string`):

What to scrape. hashtag = posts for a #tag; account = a user's profile + posts; trends = what's trending now; search = find accounts or hashtags by keyword.

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

Instance host to query (Mastodon is federated — no global API). Default mastodon.social. For account mode, use the account's HOME instance for best results.

## `searchTerms` (type: `array`):

hashtag mode: tags to pull (with or without #). search mode: keywords. Each term runs as a separate query.

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

Handles to fetch profile + posts for, e.g. 'Gargron' or 'user@another.instance'. Remote handles resolve only if known to the chosen instance.

## `trendType` (type: `string`):

Which trend feed to pull: trending statuses, hashtags, or news links.

## `searchType` (type: `string`):

Search for accounts or hashtags. (Full-text status search needs an authenticated, opted-in server and is not supported keyless — use hashtag mode for a topic feed.)

## `maxResultsPerTerm` (type: `integer`):

Maximum results per hashtag / account / search term. Higher values increase cost and run time.

## `onlyMedia` (type: `boolean`):

If true, hashtag mode returns only posts that contain images/video.

## `excludeReplies` (type: `boolean`):

If true, account mode skips the user's replies.

## `excludeReblogs` (type: `boolean`):

If true, account mode skips boosts/reblogs.

## `includeAccountProfile` (type: `boolean`):

If true, emit the account's profile as its own row before its posts.

## Actor input object example

```json
{
  "mode": "hashtag",
  "instance": "mastodon.social",
  "searchTerms": [
    "ai",
    "opensource"
  ],
  "accounts": [],
  "trendType": "statuses",
  "searchType": "accounts",
  "maxResultsPerTerm": 200,
  "onlyMedia": false,
  "excludeReplies": true,
  "excludeReblogs": false,
  "includeAccountProfile": true
}
```

# 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 = {
    "instance": "mastodon.social",
    "searchTerms": [
        "ai",
        "opensource"
    ],
    "accounts": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("navy_currant/mastodon-social-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 = {
    "instance": "mastodon.social",
    "searchTerms": [
        "ai",
        "opensource",
    ],
    "accounts": [],
}

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

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

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

```

## CLI example

```bash
echo '{
  "instance": "mastodon.social",
  "searchTerms": [
    "ai",
    "opensource"
  ],
  "accounts": []
}' |
apify call navy_currant/mastodon-social-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=navy_currant/mastodon-social-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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