Skip to main content

​
The status

Mastodon’s content unit is a Status — not a post, and not a “toot”: the API’s own endpoint, entity and field are all called status, and post belongs to Reddit throughout this API. content is plain text. The API serves an HTML fragment; Nephia strips it, because the same body is rendered in a webhook, in a feed row and in an AI prompt, and shipping markup would push a sanitising problem into all three. author.acct is always fully qualified and lowercased — alice@mastodon.social, never a bare alice. Mastodon reports a local account bare and a remote one qualified, so the same person would otherwise be two different authors depending on which instance a Watch happened to read. instance is the host the status was read from, which is not necessarily the author’s home server.

​
Coverage

Mastodon has no global keyword search, and this Source does not pretend otherwise. Full-text search on Mastodon is opt-in per user and per instance and requires an authenticated account token; a public instance serves neither. What it does serve — to anyone, documented, unauthenticated — is a hashtag timeline and an account’s statuses. Those are the two things a Watch can name. A Watch therefore requires exactly one of hashtag or account, and takes no query. Sending one is a 400 rather than a criterion we would silently discard.

​
What one instance can see

A Mastodon server shows you its federated view: the statuses its own users follow or that have otherwise reached it. A large general instance sees a great deal; a small topical one sees its own corner. Watching #yourbrand on mastodon.social is not the same as watching the whole network, and no endpoint offers the whole network. If a conversation about you lives on one particular server, watch that server. Boosts are skipped. A boost is not a mention: the original reaches the same timeline on its own, so keeping boosts would report one status once per person who shared it — and fire a webhook for each. Interval: 120–86400 seconds. Cap: 20 active Watches per Account. Each tick costs 1 credit, and an account Watch costs the same as a hashtag one even though it makes two requests — a lookup to turn the handle into an id, then the timeline.

​
What an event carries

The first tick establishes a silent baseline and emits nothing. Later ticks emit status.created with the full status. webhook_url is optional — without it the Watch still records every match, readable through GET /v1/mastodon/watches/{id}/events. See Webhooks.
Polling an account instead:
A tick narrows with since_id and also dedupes by id, so a status that federates in late still arrives exactly once. On a network of independent servers, arriving late is normal rather than exceptional.

​
Errors

An unreachable or misbehaving instance is 503 and is not charged; the Watch reports it in its activity, readable through GET /v1/mastodon/watches/{id}/activity. An instance that refuses public timelines answers 403, which is also not charged. instance is validated as a hostname when the Watch is created, and the address it resolves to is checked again on every request — a host that resolves to a private or link-local address is refused.