How to Audit a Mastodon Relay Connection With the API

Mastodon relays push public posts from one instance to many others. When your instance connects to a relay, you expect a steady stream of federated content. But sometimes the relay stops delivering posts or delivers duplicates. You need a way to verify the connection is alive and working correctly. This article explains how to use the Mastodon API to audit a relay connection, check its status, and confirm that posts are flowing as expected.

What Is a Mastodon Relay and Why Audit It?

A Mastodon relay is a special server that receives public posts from many instances and redistributes them to all connected instances. This helps small instances discover content from the wider fediverse without following every user individually. The relay maintains a list of subscribed instances and pushes new posts to each one.

When you add a relay to your instance, your server sends a subscription request. The relay accepts it and begins forwarding public posts. If the relay goes offline, changes its URL, or blocks your instance, the connection breaks silently. Your instance may show no posts from the relay for hours or days. Auditing the connection with the Mastodon API lets you detect these failures quickly.

The Mastodon API provides two main endpoints for relay management. The GET /api/v1/relays endpoint returns a list of all configured relays. Each entry includes the relay's inbox URL, the current state (pending, accepted, or rejected), and the date it was added. The GET /api/v1/instance/relays/:id endpoint gives more detail for a single relay, such as the last time it contacted your instance and any error messages.

You need administrator access to your Mastodon instance to use these API endpoints. Standard users cannot view relay configurations. You also need an access token with the admin:read and admin:write scopes. If you run a single-user instance, you are the administrator by default and can generate a token from Preferences > Development.

Steps to Audit a Mastodon Relay Connection Using the API

Follow these steps to check the relay connection on your instance and verify it is working correctly. Replace yourinstance.social with your actual Mastodon instance domain and YOUR_TOKEN with your admin access token.

1. Generate an admin access token
   Log in to your Mastodon instance as an administrator. Go to Preferences > Development > New Application. Enter a name for the application, for example “Relay Audit”. Under Scopes, select admin:read and admin:write. Click Submit. Copy the access token displayed on the next screen. Keep this token secure because it grants full admin control.
2. List all configured relays
   Open a terminal or API client such as curl or Postman. Send a GET request to https://yourinstance.social/api/v1/relays with the header Authorization: Bearer YOUR_TOKEN. The response is a JSON array. Each object in the array contains an id, inbox_url, state, and created_at field. The state field will be one of pending, accepted, or rejected. If the list is empty, your instance has no relays configured.
3. Inspect the state of each relay
   For each relay in the list, note the state value. A state of accepted means the relay has accepted your subscription and should be forwarding posts. A state of pending means the relay has not yet responded to your subscription request. A state of rejected means the relay denied your subscription, often because of a block or a configuration mismatch.
4. Get detailed status for a single relay
   To see more detail for a specific relay, send a GET request to https://yourinstance.social/api/v1/instance/relays/RELAY_ID, where RELAY_ID is the id from the list. Use the same authorization header. The response includes id, inbox_url, state, last_contact_at, error, and created_at. The last_contact_at field shows the last time the relay sent data to your instance. If this field is null or shows a date far in the past, the relay may be offline or disconnected.
5. Check the error field for failure reasons
   In the detailed response, look at the error field. If the relay has encountered a problem, this field contains a descriptive message. Common errors include Connection refused, Timeout, Invalid SSL certificate, or HTTP 403 Forbidden. These messages tell you whether the issue is on your side, the relay side, or a network problem.
6. Verify that posts from the relay appear on your instance
   After checking the API status, confirm that posts from the relay are actually appearing on your instance. Open the federated timeline in your Mastodon client. Look for posts from accounts on other instances that you have not followed directly. If the federated timeline is empty or shows only local posts, the relay may not be pushing content even if the API reports accepted status. In that case, re-add the relay using the API.
7. Re-add the relay if necessary
   If the state is rejected or the last contact is too old, remove and re-add the relay. Send a DELETE request to https://yourinstance.social/api/v1/relays/RELAY_ID with the same authorization header. Then send a POST request to https://yourinstance.social/api/v1/relays with a JSON body containing {"relay_url": "https://relay.example.com/inbox"} and the authorization header. This resets the subscription handshake.

Common Issues When Auditing Mastodon Relay Connections

Relay State Shows as Pending for More Than 24 Hours

A pending state means your instance sent a subscription request but the relay has not responded. This usually happens because the relay is offline, the relay URL is incorrect, or the relay is blocking your instance. Check the relay's website or status page to see if it is operational. Verify that the inbox URL in your relay configuration matches exactly what the relay expects, including the path and trailing slash. If the relay is a private relay, you may need to request approval from the relay operator.

Relay State Shows as Rejected

A rejected state means the relay explicitly denied your subscription. This can happen if your instance is on a blocklist maintained by the relay operator, if your instance has a poor reputation, or if the relay only accepts instances that meet certain criteria such as a minimum moderation standard. Contact the relay operator to ask why your instance was rejected. Alternatively, switch to a different public relay that has open enrollment.

Last Contact Is Recent but Federated Timeline Is Empty

If the API reports a recent last_contact_at but you see no new posts from the relay, your instance may be receiving the posts but filtering them. Check your instance's moderation settings. If you have enabled domain blocks or keyword filters, those may suppress relay posts. Also check that the relay itself is active and producing content. Some relays pause forwarding if they detect a spam wave or if their upstream instance is down.

API Returns 401 Unauthorized When Accessing Relay Endpoints

A 401 error means the access token is invalid or missing the required scopes. Regenerate the token in Preferences > Development. Ensure the token includes both admin:read and admin:write scopes. If you are using a third-party client, confirm that the client is sending the token in the Authorization header as Bearer YOUR_TOKEN. Do not send the token as a query parameter because Mastodon ignores tokens in the URL for security reasons.

Relay API Endpoints Comparison

Item	GET /api/v1/relays	GET /api/v1/instance/relays/:id
Purpose	List all configured relays on the instance	Get detailed status for a single relay
Response fields	id, inbox_url, state, created_at	id, inbox_url, state, last_contact_at, error, created_at
Required scope	admin:read	admin:read
Use case	Initial audit to see all relays	Deep investigation of a specific relay issue

You can now audit any Mastodon relay connection using the API endpoints described above. Start by listing all relays and checking their state. If a relay shows pending or rejected, investigate the error field and re-add the relay if needed. For a deeper check, compare the last contact time with the actual posts appearing on your federated timeline. If you manage multiple instances, script the API calls with curl or a tool like jq to automate regular audits and catch relay failures early.