You run a Mastodon instance and need to confirm which other servers your instance communicates with. Mastodon instances do not show a simple friends list by default. The federation dashboard gives you a directory of known remote instances, their connection status, and recent activity. This article explains how to access that dashboard and interpret the data it provides.
Key Takeaways: Viewing Your Instance’s Federated Connections
- Administration > Server > Federation: The main dashboard listing all known remote instances, their domain, software version, and connection status.
- Domain filter search box: Lets you check whether a specific domain has ever federated with your instance.
- Instance
/api/v1/instance/peersAPI endpoint: Returns a JSON array of all federated domains for programmatic access.
What the Federation Dashboard Shows
The federation dashboard is a server-side admin page. It lists every remote Mastodon instance, Pleroma instance, or other ActivityPub server that your instance has ever communicated with. Communication includes receiving a post, sending a follow, or sharing a boost. The dashboard does not require any external tool or third-party service.
Only administrators of the Mastodon instance can access the federation dashboard. Regular users cannot see the full list. If you are not the admin, you must ask the server owner to check for you.
The dashboard provides these columns for each remote instance:
- Domain: The full hostname of the remote server, for example
mastodon.social. - Software: The software the remote instance runs, such as Mastodon, Pleroma, or Friendica.
- Version: The software version reported by the remote instance.
- Connection status: Whether the instance is currently reachable, suspended, or limited.
- Last contacted: The date and time of the last successful communication.
Prerequisites for Accessing the Dashboard
You need an admin account on your Mastodon instance. The default admin account is the one created during the first server setup. If you have multiple admins, each can view the dashboard independently.
Your instance must be running Mastodon version 3.0 or later. Older versions used a different admin panel layout, but the federation data is still available through the API.
Steps to Access the Federation Dashboard
- Log in to your Mastodon instance as an administrator.
Open your instance URL in a browser and sign in with the admin account credentials. You see the home timeline after logging in. - Open the Administration menu.
Click the gear icon or your profile icon in the top right corner. Select Administration from the dropdown menu. The administration dashboard appears. - Click Server in the left sidebar.
The Server section contains settings for the entire instance. It includes the Federation option. - Click Federation.
Mastodon loads the federation dashboard. You see a paginated table of all remote instances your server has ever communicated with. The table shows up to 40 entries per page by default. - Use the search box to check a specific domain.
Type a domain name such asmastodon.socialinto the search box above the table. Press Enter. If the domain appears, your instance has federated with that server. If no results appear, your instance has never communicated with that domain. - Filter by connection status.
The dashboard includes a filter dropdown. Select All, Limited, Suspended, or Unavailable. This helps you identify instances that are currently blocked or unreachable.
Using the Peers API Endpoint
If you prefer to retrieve the federation list programmatically, Mastodon offers a public API endpoint. The endpoint returns a JSON array of domain strings. No authentication is required for this endpoint. It is read-only.
- Open a terminal or API client.
You can use curl, Postman, or any HTTP client that supports GET requests. - Send a GET request to the peers endpoint.
Use this URL structure:https://yourinstance.com/api/v1/instance/peers. Replaceyourinstance.comwith your actual domain. - Review the JSON response.
The response is a simple array of strings. Example:["mastodon.social","pleroma.example","friendica.space"]. Each string is a domain that your instance has federated with.
The peers endpoint does not include connection status or software version. For that data, you must use the admin dashboard or the authenticated admin API.
Common Issues When Viewing the Federation List
Federation Dashboard Shows No Instances
If the federation dashboard is empty, your instance may be brand new with no external communication yet. Mastodon only records instances that have sent or received at least one activity. Post publicly and wait a few hours. Check the dashboard again. If it remains empty, verify that your instance is correctly configured to federate. Check the server settings under Administration > Server > Settings. Ensure the option Enable federation is turned on.
Some Instances Appear as Limited or Suspended
A limited instance means your server has restricted its content due to moderation rules. A suspended instance means all communication is blocked. These statuses do not remove the instance from the list. They only change the connection status column. To remove an instance from the list entirely, you must delete it from the database, which is not recommended for normal administration.
API Returns an Empty Array
The peers API endpoint may return an empty array if your instance has never federated with anyone. If you know your instance has communicated with other servers, check the endpoint URL for typos. Ensure you are using HTTPS. Some older Mastodon versions require authentication for the peers endpoint. Try adding an access token as a Bearer token in the request header.
Federation Dashboard vs API Peers Endpoint
| Item | Federation Dashboard | API Peers Endpoint |
|---|---|---|
| Access method | Web browser, admin login required | HTTP GET request, no authentication needed |
| Data format | HTML table with pagination | JSON array of domain strings |
| Connection status | Yes, includes limited/suspended/unavailable | No, only domain names |
| Software version | Yes, shows remote software and version | No |
| Search by domain | Yes, search box on the dashboard | Not directly, must parse the array |
| Export capability | No native export button | Yes, copy JSON or pipe to a file |
Use the federation dashboard for quick visual checks and moderation actions. Use the API endpoint when you need to automate monitoring or integrate the list with external tools.
What to Do With the Federation List
After you see which instances federate with your server, you can make informed moderation decisions. For example, if a domain appears as limited, you can review its recent posts and decide whether to remove the limit. If a domain appears as unavailable, you can check whether it is temporarily down or permanently defunct. You can also use the list to identify instances that are running outdated software and encourage their admins to upgrade.
If you want to block a specific domain, go to Administration > Server > Federation, click the domain name, and select Suspend. The domain remains in the list but its connection status changes to Suspended. To completely remove a domain, you must delete it from the database via the Rails console, which is an advanced operation.
Regularly reviewing the federation list helps you maintain a healthy network. Check it monthly to spot unexpected connections or instances that have gone offline. The API endpoint can be used with a cron job to log changes over time.