Skip to content

How to read Mastodon profiles, posts and hashtags with one API

Updated · 3 steps

Every Mastodon server runs its own public API. Fetchproof reads any instance's public API for you, with no app token, and returns the same JSON shape for every server, so one integration and one API key cover the fediverse.

01

Look up an account

Pass the account as user@instance. You get display_name, the bio as note and as plain note_text, followers_count, following_count, statuses_count, created_at and the profile fields.

GET /v1/mastodon/profile 1 credit per call

cURL

curl --request GET 'https://api.fetchproof.com/v1/mastodon/profile?acct=Gargron%40mastodon.social' \
  --header 'x-api-key: YOUR_API_KEY'

JavaScript

const response = await fetch("https://api.fetchproof.com/v1/mastodon/profile?acct=Gargron%40mastodon.social", {
  method: 'GET',
  headers: {
    'x-api-key': process.env.FETCHPROOF_API_KEY,
  },
});
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.get(
    "https://api.fetchproof.com/v1/mastodon/profile?acct=Gargron%40mastodon.social",
    headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]},
)
print(response.json())

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  req, _ := http.NewRequest("GET", "https://api.fetchproof.com/v1/mastodon/profile?acct=Gargron%40mastodon.social", nil)
  req.Header.Set("x-api-key", os.Getenv("FETCHPROOF_API_KEY"))
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init("https://api.fetchproof.com/v1/mastodon/profile?acct=Gargron%40mastodon.social");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('FETCHPROOF_API_KEY'),
  ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Excerpt of published sample response Full response →
{
  "success": true,
  "credits_remaining": 100,
  "credits_charged": 1,
  "id": "1",
  "username": "Gargron",
  "acct": "Gargron",
  "display_name": "Eugen Rochko",
  "note": "<p>Executive Strategy &amp; Product Advisor of <span class=\"h-card\" translate=\"no\"><a href…",
  "note_text": "Executive Strategy & Product Advisor of @Mastodon. Film photography, prog metal, Dota 2. L…",
  "url": "https://mastodon.social/@Gargron",
  "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/6b2384b33799a0dd.png",
  "locked": false,
  "…": "6 more fields"
}
02

Page through the account's posts

Returns one page of the account's public statuses. Each has content as HTML and as plain text, created_at, language, replies_count, reblogs_count, favourites_count, media and tags. To page back, pass the last status's id as max_id. You can pass id with instance instead of acct.

GET /v1/mastodon/account/statuses 1 credit per call

cURL

curl --request GET 'https://api.fetchproof.com/v1/mastodon/account/statuses?acct=Gargron%40mastodon.social' \
  --header 'x-api-key: YOUR_API_KEY'

JavaScript

const response = await fetch("https://api.fetchproof.com/v1/mastodon/account/statuses?acct=Gargron%40mastodon.social", {
  method: 'GET',
  headers: {
    'x-api-key': process.env.FETCHPROOF_API_KEY,
  },
});
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.get(
    "https://api.fetchproof.com/v1/mastodon/account/statuses?acct=Gargron%40mastodon.social",
    headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]},
)
print(response.json())

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  req, _ := http.NewRequest("GET", "https://api.fetchproof.com/v1/mastodon/account/statuses?acct=Gargron%40mastodon.social", nil)
  req.Header.Set("x-api-key", os.Getenv("FETCHPROOF_API_KEY"))
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init("https://api.fetchproof.com/v1/mastodon/account/statuses?acct=Gargron%40mastodon.social");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('FETCHPROOF_API_KEY'),
  ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Excerpt of published sample response Full response →
{
  "success": true,
  "credits_remaining": 100,
  "credits_charged": 1,
  "statuses": [
    {
      "id": "117625510556328060",
      "created_at": "2026-11-16T09:54:13.954Z",
      "url": "https://mastodon.social/@Gargron/117625510556328060",
      "content": "<p><span class=\"h-card\" translate=\"no\"><a href=\"https://mastodon.social/@myrtlears\" class=…",
      "text": "@myrtlears @Mastodon They’re going through customs on the way to our warehouse right now, …",
      "spoiler_text": "",
      "sensitive": false,
      "language": "en",
      "replies_count": 0,
      "reblogs_count": 0,
      "favourites_count": 1,
      "in_reply_to_id": "117625211993762938",
      "…": "4 more fields"
    }
  ],
  "next_max_id": "117594584826683382"
}
03

Read a hashtag timeline

Pass a tag, with or without #, and the instance to read it from. The timeline is that instance's public view of the tag, so it includes posts from other fediverse servers it knows about. Different instances can return different results.

GET /v1/mastodon/hashtag 1 credit per call

cURL

curl --request GET 'https://api.fetchproof.com/v1/mastodon/hashtag?hashtag=photography&instance=mastodon.social' \
  --header 'x-api-key: YOUR_API_KEY'

JavaScript

const response = await fetch("https://api.fetchproof.com/v1/mastodon/hashtag?hashtag=photography&instance=mastodon.social", {
  method: 'GET',
  headers: {
    'x-api-key': process.env.FETCHPROOF_API_KEY,
  },
});
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.get(
    "https://api.fetchproof.com/v1/mastodon/hashtag?hashtag=photography&instance=mastodon.social",
    headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]},
)
print(response.json())

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  req, _ := http.NewRequest("GET", "https://api.fetchproof.com/v1/mastodon/hashtag?hashtag=photography&instance=mastodon.social", nil)
  req.Header.Set("x-api-key", os.Getenv("FETCHPROOF_API_KEY"))
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init("https://api.fetchproof.com/v1/mastodon/hashtag?hashtag=photography&instance=mastodon.social");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('FETCHPROOF_API_KEY'),
  ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Excerpt of published sample response Full response →
{
  "success": true,
  "credits_remaining": 100,
  "credits_charged": 1,
  "hashtag": "photography",
  "statuses": [
    {
      "id": "117628237828267270",
      "created_at": "2026-11-16T21:27:45.000Z",
      "url": "https://pixelfed.social/p/CURTISSH/1028056062082996867",
      "content": "<a href=\"https://pixelfed.social/discover/tags/sunset?src=hash\" class=\"u-url hashtag\" rel=…",
      "text": "#sunset over #boston #ocean #coastal #goldenhour #massachusetts #newengland #photography",
      "spoiler_text": "",
      "sensitive": false,
      "language": null,
      "replies_count": 0,
      "reblogs_count": 0,
      "favourites_count": 0,
      "in_reply_to_id": null,
      "…": "4 more fields"
    }
  ],
  "next_max_id": "117628032750983946"
}

What it costs

Each call costs 1 credit. An empty page of statuses or hashtag posts costs 0, and cache_max_age serves a recent cached copy for 0 credits.

Limits

Only public posts are returned, as each instance shows them to signed-out visitors. An instance can restrict its public API, and then its data isn't available.

Try it with 100 free credits

Sign up with an email address, no card. Credits never expire. Errors cost 0 credits, and each endpoint page lists exactly what it charges.