Tutorials
Mastodon profile in JavaScript
One authenticated call to /api/v1/mastodon/profile?handle=Gargron@mastodon.social, the response it returned, and the line that reads one field out of it.
What you need
Node 18 or later, where fetch is global. No package to install. The same code runs in a browser, except that a browser would expose your key — call this from your server.
The call
const url = "https://honesthook.com/api/v1/mastodon/profile?handle=Gargron@mastodon.social";
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.HH_KEY}` },
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
const envelope = await response.json();
console.log(envelope.success, envelope.platform, envelope.endpoint);
What came back
{
"success": true,
"platform": "mastodon",
"endpoint": "mastodon/profile",
"data": {
"author": {
"id": "https://mastodon.social/users/Gargron",
"handle": "Gargron@mastodon.social",
"name": "Eugen Rochko",
"followers": 382854,
"following": 743,
"posts_count": 82332,
"verified": null,
"is_private": false
}
},
"error": null,
"cached": false
}
Recorded response, captured 27 Sep 2026. A live call returns the value at the moment you ask, not this one.
Every field in that capture
| In JavaScript | Type in this capture |
|---|
envelope.success | boolean |
envelope.platform | string |
envelope.endpoint | string |
envelope.data.author.id | string |
envelope.data.author.handle | string |
envelope.data.author.name | string |
envelope.data.author.followers | number |
envelope.data.author.following | number |
envelope.data.author.posts_count | number |
envelope.data.author.verified | null |
envelope.data.author.is_private | boolean |
envelope.error | null |
envelope.cached | boolean |
A field we cannot read comes back null, never 0. A zero would be a claim about the account; null is a fact about our collection. The full list of what this route does not return is on mastodon-api/profile.
Reading one field
console.log(envelope.data.author.followers);
envelope is the object from the block above. Keep the key on the server: a key shipped to a browser is a key anyone can read.
Mastodon is not one site. It is thousands of servers that agree on a protocol, and that single fact decides how you call this endpoint.
The handle must carry its instance
@name on its own identifies nobody on a federated network — the same local name exists on hundreds of servers, belonging to different people. So the handle here is always user@instance, and a handle without an instance is refused with a 400 rather than guessed at.
The same logic governs the id you get back: it is the ActivityPub URI, not a number. Numeric ids are local to one server, and the same account has a different one on every instance that has seen it. A number would look tidier and would be wrong the moment you compared two instances.
What you are calling
One authenticated GET to our endpoint, with your key in an Authorization header. The request is routed to the account's own origin instance, which is the authoritative one. The handle in the example is the one that produced the recorded response below — note the @ inside the query string; it is legal there and needs no escaping.
Before you copy the block
Keep the key in an environment variable — all three examples read HH_KEY. Then read the field list: Mastodon verifies links, not identities, so the verified field stays null instead of reporting a link check as an identity check.
The endpoint itself
Parameters, the handle format, what the route does not return and what a call costs: mastodon-api/profile.
The same call in curl · Python.