Mastodon Post Schedule: How to Set Future Publish Time From the API

Mastodon does not include a built-in post scheduler in its web interface or official mobile apps. If you want to publish a post at a future time, you must use the Mastodon REST API directly or through a third-party client. The API includes a scheduled_at parameter that accepts an ISO 8601 timestamp. This article explains how to construct the API request, authenticate, and set a future publish time using a simple HTTP call. You will learn the exact endpoint, required headers, and common pitfalls when scheduling a post.

How the Mastodon Scheduling API Works

The Mastodon API treats scheduled posts as a separate resource type. When you include a scheduled_at value in the status creation call, the server does not publish the status immediately. Instead, it creates a ScheduledStatus object that the server processes at the given time. The server stores the post content, media attachments, and visibility settings in the scheduled object. The API returns a ScheduledStatus ID that you can use to modify or cancel the post before it goes live.

To schedule a post, you need a Mastodon account on any instance and an OAuth access token with the write:statuses scope. You can generate this token through the Mastodon web interface under Preferences > Development > New Application. The token must have at least the write:statuses scope. Without the correct scope, the API returns a 403 Forbidden error. The scheduling feature works on Mastodon version 3.0.0 and later. Instances running older versions ignore the scheduled_at parameter and publish the post immediately.

ISO 8601 Timestamp Requirements

The scheduled_at value must be a string in ISO 8601 format. Mastodon accepts timestamps with timezone offsets, but the server converts them to UTC for storage. The safest approach is to send the timestamp in UTC with the Z suffix. For example, 2025-04-15T14:30:00Z represents 2:30 PM UTC on April 15, 2025. If you send a timestamp with a timezone offset like +02:00, the server subtracts the offset and stores the UTC equivalent. The server rejects timestamps in the past. If you send a time earlier than the current server time, the API returns a 422 Unprocessable Entity error.

Steps to Schedule a Mastodon Post Using the API

The following steps assume you have a Mastodon account and an access token with the write:statuses scope. You can use any HTTP client such as cURL, Postman, or a programming language like Python. The examples use cURL for clarity.

1. Generate an OAuth access token with write:statuses scope
   Log in to your Mastodon instance. Go to Preferences > Development > New Application. Enter an application name such as “Scheduler”. Under Scopes, select write:statuses. Click Submit. Copy the access token displayed on the next page. Store this token securely.
2. Construct the POST request to /api/v1/statuses
   Set the HTTP method to POST. Use the URL https://your-instance.example/api/v1/statuses. Replace your-instance.example with your actual Mastodon instance domain. Set the Authorization header to Bearer YOUR_ACCESS_TOKEN. Replace YOUR_ACCESS_TOKEN with the token from step 1.
3. Add the status parameter with post content
   In the request body, include the status parameter. This parameter holds the text of your post. The maximum length depends on your instance configuration. For example: "status": "This post is scheduled via the Mastodon API."
4. Add the scheduled_at parameter with the future timestamp
   Include the scheduled_at parameter in the request body. The value must be an ISO 8601 string. For example: "scheduled_at": "2025-04-15T14:30:00Z". Ensure the timestamp is at least one minute in the future. The server rejects timestamps less than 60 seconds ahead.
5. Send the request and verify the response
   Send the POST request. A successful response returns HTTP 200 with a JSON object. The object contains an id field that is the ScheduledStatus ID. If you receive a 422 error, check the timestamp format and ensure it is in the future. If you receive a 403 error, verify your token includes the write:statuses scope.

Common Scheduling API Mistakes and How to Avoid Them

API Returns 422 Unprocessable Entity Error

This error most often occurs because the scheduled_at timestamp is in the past or less than 60 seconds in the future. The server also rejects timestamps that are more than 365 days in the future. Verify the timestamp is in ISO 8601 format with a Z suffix. Use a tool like Epoch Converter to confirm the UTC time. If you are generating the timestamp programmatically, ensure your system clock is accurate and set to UTC.

Post Published Immediately Instead of at the Scheduled Time

The most common cause is a missing or misspelled scheduled_at parameter. The API ignores unknown parameters. If the parameter name is not exactly scheduled_at, the server treats the request as a normal immediate post. Check the request body for typos. Another cause is using an instance running Mastodon version earlier than 3.0.0. Older versions do not recognize the parameter. You can check the instance version by visiting https://your-instance.example/api/v1/instance and looking at the version field.

Cannot Cancel or Modify a Scheduled Post

To cancel a scheduled post, send a DELETE request to /api/v1/scheduled_statuses/{id} where {id} is the ScheduledStatus ID from the creation response. To modify the content or time, you must delete the scheduled status and create a new one. The API does not support updating an existing scheduled status. You can list all scheduled posts by sending a GET request to /api/v1/scheduled_statuses. The response includes an array of scheduled status objects with their IDs and scheduled times.

Scheduled Post vs Immediate Post: Key Differences

Item	Scheduled Post	Immediate Post
API endpoint	POST /api/v1/statuses with scheduled_at	POST /api/v1/statuses without scheduled_at
Response type	ScheduledStatus object with id	Status object with id
Time constraint	Must be 60 seconds to 365 days in the future	No time constraint
Modification	Delete and recreate; no update endpoint	Can be edited via PUT /api/v1/statuses/{id}
Visibility support	Public, unlisted, private, direct	Public, unlisted, private, direct

The scheduling API supports all visibility levels including direct messages. Media attachments can be included by uploading them first via POST /api/v1/media and then referencing the media IDs in the status creation call. The scheduled_at parameter works with the media_ids parameter. The server validates media attachments before scheduling. If a media attachment fails processing, the scheduled post is still created but the post may have missing media when published. Always verify media processing status before scheduling.

You can now schedule Mastodon posts from any API-capable tool using the scheduled_at parameter on the /api/v1/statuses endpoint. Start by generating an OAuth token with the write:statuses scope. Test with a non-sensitive post at least 2 minutes in the future. For advanced automation, combine the scheduling endpoint with a cron job or a serverless function that calls the API at regular intervals. Remember to handle the 422 error by validating the timestamp against the server clock using the /api/v1/instance endpoint to fetch the server time.