Mastodon Bot Account Marker: How to Set for API-Driven Posters

If you run an automated poster on Mastodon, the platform expects you to mark your account as a bot. Without this marker, your automated posts may get rate-limited more aggressively or flagged by other users and instances. The bot flag is a simple boolean setting that tells the Mastodon API and other servers that this account posts programmatically. This article explains exactly what the bot account marker does, how to enable it through the web interface and the API, and what changes once you set it.

What the Bot Account Marker Does and Why It Matters

The bot account marker is a metadata flag stored in your Mastodon account settings. When you enable it, Mastodon adds a small robot icon badge next to your account name on your profile page. This badge is visible to all users and instances that federate with you. The marker does not change your ability to post, follow, or be followed. It signals that the account operates under automated control rather than direct human use.

Mastodon instances can use the bot flag to adjust rate limits. Many instances apply stricter rate limits to accounts without the bot flag that post at high frequency. With the bot flag, the instance may allow a higher posting cadence because it expects automated behavior. The flag also helps other users decide whether to follow or mute your account. Some Mastodon clients and filters let users hide bot accounts from their timelines entirely.

From an API perspective, the bot flag is part of the credentials object you can read and write using the Mastodon REST API. When you authenticate with OAuth, your access token has scopes that determine whether you can update the bot field. The scope write:accounts is required to change the bot marker through the API. Without this scope, the API call will fail with a 403 Forbidden error.

Prerequisites for Setting the Bot Marker

Before you proceed, confirm that you have the following:

• A Mastodon account on an instance that supports the bot flag (all current Mastodon versions support it).
• Access to the account either through the web interface or an API access token with the write:accounts scope.
• If using the API, a registered application on your instance that generated the access token.

How to Enable the Bot Marker Through the Web Interface

The web interface method is the simplest option for single accounts or testing. You do not need any programming knowledge. Follow these steps exactly.

1. Open your profile settings
   In any Mastodon web client, click the gear icon in the right sidebar or go directly to Preferences. On mobile, tap your avatar in the bottom bar and select Preferences.
2. Navigate to the Profile section
   From the Preferences menu, click or tap Profile. This section contains your display name, bio, avatar, header image, and the bot account toggle.
3. Enable the bot account toggle
   Scroll down until you see the checkbox labeled This is a bot account. Check the box. The label does not change, but the box now shows a checkmark.
4. Save your changes
   Click the Save Changes button at the bottom of the Profile page. A green confirmation banner appears at the top of the page stating Your changes have been saved.
5. Verify the bot badge appears
   Go to your public profile page. You should see a small robot icon next to your display name. If you do not see it, refresh the page or log out and back in.

How to Set the Bot Marker Through the Mastodon API

For developers running multiple bot accounts or integrating the setting into a deployment script, use the API. The endpoint is PATCH /api/v1/accounts/update_credentials. The request body must include the bot field set to true or false.

1. Obtain an access token with write:accounts scope
   Register an application on your Mastodon instance using the API. Use the authorization code flow or the client credentials flow. Ensure the scope list includes write:accounts. Save the access token in a secure environment variable.
2. Prepare the API request
   Use a tool like curl, Python requests, or any HTTP client. Set the HTTP method to PATCH. Set the Authorization header to Bearer YOUR_ACCESS_TOKEN. Set the Content-Type header to application/json.
3. Send the request body
   The JSON body must contain the key bot with a boolean value. Example: {"bot": true}. For curl, the command looks like this:
   curl -X PATCH -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"bot": true}' https://yourinstance.social/api/v1/accounts/update_credentials
4. Check the response
   A successful response returns a 200 OK status with the updated account credentials object in the JSON body. Look for the bot field. It should be true. If you receive a 422 Unprocessable Entity, the bot field was not accepted. Check that the token has the correct scope.
5. Verify the change on the profile page
   Open the account profile in a web browser. Confirm the robot badge appears. If you do not see the badge, the API call may have succeeded but the instance cached the old profile. Wait a few minutes and refresh.

Common Issues When Setting the Bot Marker

“This is a bot account” checkbox is missing

The checkbox appears only on Mastodon version 3.0.0 and later. If you run an older instance or a fork that removed the option, you may not see it. Upgrade your Mastodon instance to the latest stable release. Alternatively, use the API method which works on all versions that support the bot field.

API returns 403 Forbidden when updating bot flag

This error means your access token lacks the write:accounts scope. Generate a new token with the correct scope. If you use the client credentials flow, note that it does not support user-level scopes. Use the authorization code flow instead and approve the write:accounts scope during the OAuth dialog.

Bot badge does not appear after setting the flag

The badge may not render immediately due to caching on the instance or in your browser. Clear your browser cache and reload the profile. If the badge still does not appear, check that you saved the settings in the web interface or that the API response included "bot": true. Some Mastodon forks or custom themes hide the bot badge even when the flag is set.

Bot Account vs Regular Account: Key Differences

Item	Bot Account	Regular Account
Profile badge	Robot icon displayed next to name	No special badge
Default post visibility	Often set to unlisted by the API	Public by default
Rate limits	May allow higher posting frequency	Stricter limits for automated posting
Discoverability in filters	Can be hidden by users who mute bots	Not affected by bot filters
API scope needed to set	write:accounts	Not applicable

Now you can set the bot marker on any Mastodon account using either the web interface or the API. If you run multiple automated posters, write a script that calls the PATCH endpoint after account creation. This ensures every new bot account is correctly flagged from the start. Remember that the bot flag is permanent until you change it again. Use the PATCH /api/v1/accounts/update_credentials endpoint with {"bot": false} to remove the marker if you later convert the account to a human-operated profile.