Mastodon Instance Federation Statistics: How to Read on the API

Mastodon instance administrators often need to monitor how well their server connects with other instances across the fediverse. Federation statistics show the number of known instances, active users, and posts exchanged. The Mastodon API provides these metrics through a dedicated endpoint. This article explains how to access the /api/v1/instance endpoint and interpret the federation data it returns.

What the Mastodon Instance API Endpoint Returns

The Mastodon API endpoint /api/v1/instance is an unauthenticated GET request. It returns a JSON object containing the instance name, description, contact information, and a stats object. The stats object has three fields: user_count, status_count, and domain_count. These fields are updated periodically by the Mastodon background job Scheduler::InstanceRefreshScheduler, which runs every 15 minutes by default.

user_count is the number of registered users on this instance only. It does not count users from other instances. status_count is the number of posts (toots) created by local users. domain_count is the number of unique remote domains (instances) that this server has ever discovered or communicated with. A domain is counted once, regardless of how many users or posts it represents.

The endpoint also includes a configuration object with federation limits such as statuses_max_reblogs and media_attachments_allowed_mime_types. However, the federation statistics are limited to the three fields in stats. For deeper federation metrics, you need to query additional API endpoints like /api/v1/instance/peers and /api/v1/instance/activity.

How the Data Is Collected

Mastodon maintains a local database table called accounts and a table called statuses. The domain_count is derived from the accounts table: it counts distinct domain values from all remote accounts that have been seen at least once. When a remote user sends a post to your instance, Mastodon creates an account entry for that domain. This means the domain_count reflects every domain that has ever interacted with your instance, even if that interaction was a single follow or a single post.

Steps to Retrieve and Interpret Federation Statistics

1. Send a GET request to the API endpoint
   Use a tool like curl or a browser. The URL is https://yourinstance.social/api/v1/instance. Replace yourinstance.social with the actual domain of your Mastodon server. No authentication is required.
2. Examine the stats object in the JSON response
   The response contains a stats field. Example: "stats": {"user_count": 1200, "status_count": 45000, "domain_count": 850}. The domain_count of 850 means this instance has communicated with 850 other Mastodon instances.
3. Check the user_count for local user growth
   A rising user_count indicates new registrations. A flat count suggests registration is closed or no new users are joining. Compare this with status_count to see if existing users are actively posting.
4. Use /api/v1/instance/peers for a list of federated domains
   Send a GET request to https://yourinstance.social/api/v1/instance/peers. This returns an array of domain strings, such as ["mastodon.social", "fosstodon.org"]. This list is the same set that contributes to domain_count.
5. Use /api/v1/instance/activity for weekly activity
   Send a GET request to https://yourinstance.social/api/v1/instance/activity. This returns an array of objects with week (Unix timestamp), statuses (local posts created that week), logins (number of active users), and registrations (new users). This gives a time-series view of federation activity.

Common Mistakes When Reading Federation Statistics

Misinterpreting user_count as Global User Count

New administrators often assume user_count represents all users across the fediverse. It does not. The field only counts users registered on your specific instance. To see the total number of users across all federated instances, you would need to aggregate data from each instance’s API, which is impractical at scale. Mastodon does not provide a global user count.

Assuming domain_count Equals Number of Active Connections

domain_count counts every domain that has ever interacted with your instance, including domains that are now defunct or have blocked your instance. A high domain_count does not mean your instance is actively federating with all those domains. To check active federation, you can compare the domain_count with the number of domains that have sent posts in the last 30 days using the /api/v1/instance/activity endpoint and server logs.

Relying on Stale Data

The stats object is refreshed every 15 minutes by the Scheduler::InstanceRefreshScheduler. If you make a change like adding a new user or blocking a domain, the statistics may not update immediately. You can force a refresh by restarting the Mastodon background workers or by running the scheduler manually with RAILS_ENV=production bin/tootctl refresh_instance_stats on the server command line.

Mastodon API Endpoints for Federation Data

Endpoint	Data Returned	Authentication Required
/api/v1/instance	Instance metadata including stats object with user_count, status_count, domain_count	No
/api/v1/instance/peers	Array of domain strings that have ever federated with this instance	No
/api/v1/instance/activity	Array of weekly objects with week, statuses, logins, registrations	No

The /api/v1/instance/peers endpoint is useful for building a list of federated instances. The /api/v1/instance/activity endpoint provides historical trends. None of these endpoints require authentication, making them suitable for monitoring tools and public dashboards.

You can now query the Mastodon instance API to retrieve federation statistics and interpret the user_count, status_count, and domain_count fields correctly. Use the /api/v1/instance/peers endpoint to get a full domain list and /api/v1/instance/activity for weekly trends. For real-time data, consider setting up a cron job that calls the API every five minutes and logs the results.