# Mastodon Scraper - Posts by Hashtag, Account or Instance (`turboextract/mastodon-posts-hashtags`) Actor

Mastodon posts by hashtag, account or instance timeline: text, link, date, language, replies, boosts, favourites, hashtags, media, link card and author with followers. Works on mastodon.social and any other instance through the public API. No login.

- **URL**: https://apify.com/turboextract/mastodon-posts-hashtags.md
- **Developed by:** [Moses Ndambuki](https://apify.com/turboextract) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$3.00 / 1,000 post delivereds

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/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 Scraper: Posts by Hashtag, Account or Instance

**Export Mastodon posts by hashtag, account or instance timeline, with text, date, language, replies, boosts, favourites, hashtags, media, link card and author details.** Works on mastodon.social and any other Mastodon server through the public API. No login.

In one test, the actor returned 45 recent #opensource posts and 45 posts from a well-known account in a few seconds, each with the author's follower count.

***

### Who this is for

- **Brands and PR teams** tracking hashtags and mentions on the fediverse
- **Social media managers** finding posts and people to engage with
- **Researchers** studying public conversation on Mastodon
- **Developer relations teams** following tech and open-source hashtags
- **AI and data teams** collecting public social posts

***

### What you get

```json
{
  "id": "117650485816558626",
  "url": "https://example.social/@username/117650485785798925",
  "text": "Has AI Solved Reverse Engineering? ... #linux #opensource",
  "createdAt": "2026-11-20T19:45:45.000Z",
  "language": "en",
  "replies": 0,
  "boosts": 0,
  "favourites": 0,
  "hashtags": ["linux", "opensource"],
  "linkCard": { "url": "https://youtu.be/...", "title": "Has AI Solved Reverse Engineering?" },
  "authorHandle": "username@example.social",
  "authorName": "Author name",
  "authorFollowers": 17,
  "source": "#opensource"
}
```

***

### How it works

```mermaid
flowchart LR
    A[Hashtags] --> D[Public Mastodon API]
    B[Accounts] --> D
    C[Instance timeline] --> D
    D --> E[Filter: replies, boosts, language, keywords, date]
    E --> F[Post rows with author]
```

***

### Quick start

1. Click **Try for free**.
2. Add **Hashtags**, **Accounts**, or turn on **Instance timeline**.
3. Optional: **Keywords**, **Language** or **Posted within (days)**.
4. Change the **Instance** if you want a server other than mastodon.social.
5. Click **Start**, then export to CSV, JSON or Google Sheets.

#### API

```bash
curl -X POST "https://api.apify.com/v2/acts/Turboextract~mastodon-posts-hashtags/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hashtags": ["opensource", "selfhosted"], "language": "en", "postedWithinDays": 1}'
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("Turboextract/mastodon-posts-hashtags").call(run_input={
    "accounts": ["https://mastodon.social/@username"],
    "maxResultsPerSource": 200,
})
for p in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(p["createdAt"], p["favourites"], p["text"][:80])
```

***

### Input

| Field | Default | What it does |
|---|---|---|
| `hashtags` | – | Without the # |
| `accounts` | – | `user@server` or profile URLs |
| `instanceTimeline` | false | Newest local posts on the instance |
| `instance` | mastodon.social | Server for hashtags and timeline |
| `keywords` | – | Match post text |
| `language` | all | Language code, like `en` |
| `excludeReplies` | true | Skip replies |
| `excludeBoosts` | true | Skip reposts |
| `postedWithinDays` | 0 (all) | Only recent posts |
| `maxResultsPerSource` | 100 | Per hashtag or account |
| `maxResults` | 500 | Total cap per run |

***

### Pricing

**$0.003 per post delivered.** 1,000 posts cost $3.

| Option | 1,000 posts |
|---|---|
| **Mastodon Scraper** | **$3**, hashtags, accounts and timelines |
| Other Mastodon actors on Apify | $0.05 to $3 |
| Social listening tools | $50+ a month |

***

### Use cases

- **Hashtag tracking**: every #yourbrand post, every hour
- **Influencer research**: active accounts with followers in your niche
- **Event coverage**: conference hashtags during the event
- **Content research**: what tech and open-source people share
- **Archiving**: a backup of an account's public posts

***

### Tips

- Hashtag timelines show posts the instance knows about. mastodon.social is the largest, so it sees the most.
- Account posts come from the account's own server, so they are complete.
- Dedupe on `url` across scheduled runs.
- For Bluesky, use [Bluesky Scraper](https://apify.com/Turboextract/bluesky-posts-profiles).

***

### Pairs well with

- [Bluesky Scraper](https://apify.com/Turboextract/bluesky-posts-profiles): posts and profiles from Bluesky
- [Lemmy Scraper](https://apify.com/Turboextract/lemmy-posts-comments): fediverse forum posts and comments
- [Telegram Channel Scraper](https://apify.com/Turboextract/telegram-channel-scraper): public channel posts

***

### FAQ

**Do I need a Mastodon account?** No. The actor uses the public API.

**Can it search all posts by keyword?** Mastodon only allows full-text search when signed in, so use hashtags or accounts, then filter with **Keywords**.

**Which servers work?** Any Mastodon server that allows public timelines, which is most of them.

**How fast is it?** About 40 posts per request, a few hundred posts in seconds.

**Is it legal?** It reads public posts through Mastodon's open API.

***

### Support

- Docs and examples: https://github.com/andersonjames38phd-cpu/mastodon-posts-hashtags
- Community Discord: https://discord.gg/8SrXSCpvgj

Built and maintained by [Turboextract](https://apify.com/Turboextract) on the Apify platform.

# Actor input Schema

## `hashtags` (type: `array`):

Hashtags without the #, like opensource.

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

Handles or profile URLs, like Gargron@mastodon.social or https://mastodon.social/@Gargron.

## `instanceTimeline` (type: `boolean`):

Also read the newest public posts on the instance itself.

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

Mastodon server for hashtags and the timeline.

## `keywords` (type: `array`):

Keep posts whose text contains one of these.

## `language` (type: `string`):

Only posts in this language code, like en. Empty for all.

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

Skip posts that reply to someone.

## `excludeBoosts` (type: `boolean`):

Skip reposts of other people's posts.

## `postedWithinDays` (type: `integer`):

Only posts from the last N days. 0 means no limit.

## `maxResultsPerSource` (type: `integer`):

Newest first.

## `maxResults` (type: `integer`):

Stop after this many posts in total. You only pay for what is delivered.

## Actor input object example

```json
{
  "hashtags": [
    "opensource"
  ],
  "instanceTimeline": false,
  "instance": "mastodon.social",
  "excludeReplies": true,
  "excludeBoosts": true,
  "postedWithinDays": 0,
  "maxResultsPerSource": 100,
  "maxResults": 500
}
```

# Actor output Schema

## `results` (type: `string`):

One row per post with text, engagement, hashtags and author.

# 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 = {
    "hashtags": [
        "opensource"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("turboextract/mastodon-posts-hashtags").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 = { "hashtags": ["opensource"] }

# Run the Actor and wait for it to finish
run = client.actor("turboextract/mastodon-posts-hashtags").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 '{
  "hashtags": [
    "opensource"
  ]
}' |
apify call turboextract/mastodon-posts-hashtags --silent --output-dataset

```

## MCP server setup

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

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/ZFf1wTAPr3A2nPFW3/builds/Jp1Fa0dawi22ya7cq/openapi.json
