Mastodon Export Specific Date Range: How to Filter With API

Mastodon lets you export your data from the Preferences menu. But the built-in export tool has no option to limit the export to a specific date range. You can only export all your toots, followers, and lists at once. This article explains how to use the Mastodon API to request data for a custom time window. You will learn to write API calls that filter your posts, favorites, and other records by date.

How the Mastodon API Handles Date Filtering

The Mastodon API does not accept direct date strings like 2024-01-01 in most endpoints. Instead, it uses numeric IDs that encode the creation time of each record. Every toot, follow, and favorite has a unique integer ID. The ID increases over time. Newer records have higher IDs than older ones.

To filter by date, you must first find the ID that corresponds to the start or end date you want. You then pass that ID as the since_id or max_id parameter in the API request. The server returns only records with IDs above since_id or below max_id. This approach lets you export data for a specific month, week, or custom period.

Understanding since_id and max_id

The two parameters work as follows:

• since_id — Returns only records with an ID greater than this value. Use it to get data after a certain date.
• max_id — Returns only records with an ID less than or equal to this value. Use it to get data before a certain date.

Combine both parameters to define a window. For example, to get toots from January 2024, you set since_id to the ID of the last toot of December 2023 and max_id to the ID of the last toot of January 2024.

Prerequisites for Using the API

You need three things before you start:

1. A Mastodon account with API access
   Any Mastodon account works. You do not need special permissions for reading your own data.
2. An access token
   Generate a token from Preferences > Development > New Application. Give it at least the read scope.
3. A tool to make HTTP requests
   You can use curl in a terminal, Postman, or any programming language with an HTTP library.

Steps to Export Toots Within a Date Range

Follow these steps to export your toots for a specific time period. The same method works for favorites and follows with different endpoints.

1. Get your account ID
   Send a GET request to https://yourinstance.social/api/v1/accounts/verify_credentials with your access token in the Authorization header. The response includes an id field. Copy that number.
2. Find the ID for your start date
   Mastodon IDs are based on the Unix timestamp. Use a tool like the Mastodon ID converter at https://mastodon.social/convert or write a script that converts a timestamp to a Mastodon ID. For January 1, 2024 at 00:00 UTC, the ID is approximately 111111111111111111 (actual value depends on instance uptime).
3. Find the ID for your end date
   Use the same converter for the last second of your target month. For January 31, 2024 at 23:59 UTC, convert that timestamp to an ID.
4. Send the API request with date range
   Call GET https://yourinstance.social/api/v1/accounts/:id/statuses?since_id=START_ID&max_id=END_ID&limit=40. Replace :id with your account ID, START_ID with the ID from step 2, and END_ID with the ID from step 3. The limit parameter controls how many toots per page (max 40).
5. Handle pagination for large exports
   If you have more toots than the limit, the response includes a Link header with a next URL. Follow that URL to get the next page. The next URL already contains the correct max_id for the next batch.
6. Save the results
   Write each page of the response to a JSON file. Combine all files later to get the complete export for your date range.

Example curl Command for a Single Page

Replace yourinstance.social, YOUR_ACCOUNT_ID, START_ID, END_ID, and YOUR_TOKEN with your actual values:

curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://yourinstance.social/api/v1/accounts/YOUR_ACCOUNT_ID/statuses?since_id=START_ID&max_id=END_ID&limit=40"

Common Issues and How to Avoid Them

You Get an Empty Response Even Though You Have Posts in That Period

The most likely cause is an incorrect ID conversion. Mastodon IDs are not simply the Unix timestamp multiplied by 1000. They use a snowflake algorithm that includes the instance’s internal timestamp offset. Use the official Mastodon ID converter or calculate the ID using the instance’s creation timestamp. If your instance is old, the ID for a given date will be higher than on a newer instance.

API Returns a 401 Unauthorized Error

Your access token may lack the read scope or has expired. Go to Preferences > Development > Edit your app and check the scopes. Regenerate the token if needed. Ensure you include the token in the Authorization header as Bearer YOUR_TOKEN.

Pagination Stops Before All Posts Are Retrieved

The API has rate limits. If you send requests too fast, the server may return a 429 Too Many Requests error. Wait for the time specified in the Retry-After header before continuing. Also check that you are following the next URL from the Link header exactly. Do not modify the parameters manually.

Mastodon API Endpoints for Date-Range Exports

Data Type	Endpoint	Filter Parameters
Toots	GET /api/v1/accounts/:id/statuses	since_id, max_id, limit
Favorites	GET /api/v1/favourites	max_id, since_id, limit
Follows (accounts you follow)	GET /api/v1/accounts/:id/following	since_id, max_id, limit
Followers	GET /api/v1/accounts/:id/followers	since_id, max_id, limit
Lists	GET /api/v1/lists	No date filtering (all lists returned)

The lists endpoint does not support date filtering because lists are metadata, not chronological records. For bookmarks, use GET /api/v1/bookmarks with max_id and since_id.

You can now export your Mastodon data for any custom date range using the API. Start with a small test to verify your ID conversion. Write a script that loops through paginated results to automate larger exports. For advanced use, consider using the min_id parameter instead of since_id in some endpoints for better performance with very old data.