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.
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.
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; {
"success": true,
"credits_remaining": 100,
"credits_charged": 1,
"id": "1",
"username": "Gargron",
"acct": "Gargron",
"display_name": "Eugen Rochko",
"note": "<p>Executive Strategy & 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"
} 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.
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; {
"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"
} 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.
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; {
"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.