Troubleshooting: Recurring Event Instances Out of Order (Master Event Filtering)

Question: Why are recurring event instances not returned in strict chronological order when using the master_event_id parameter?

When retrieving instances of recurring events using the master_event_id parameter, the events may not be returned in strict chronological order by start_time. This behavior is expected due to how calendar providers process recurrence rules.

Root Cause: Provider Processing Order

The Nylas API v3 queries calendar providers (Google, Microsoft, etc.) in real-time and returns data exactly as provided by the provider. The provider's internal system often processes complex recurrence rules—especially those containing exceptions, modifications, or overrides—in an order based on the recurrence rule logic, not strict chronological order.

This results in a list where regular occurrences and exceptions are chunked together, leading to a seemingly random order.

Expected Behavior:

• Master recurring events and standalone events are typically sorted by start_time.
• Recurring event instances filtered by master_event_id may appear out of chronological order due to provider-side processing.

Workaround (Client-Side Fix)

If your application requires strict chronological ordering of recurring event instances, you must sort the results client-side after receiving them from the API using the start_time field.

Example (JavaScript):

// Sort events by start_time after receiving from API
events.sort((a, b) => a.when.start_time - b.when.start_time);

Docs for reference:
 
Using the Events API
Working with recurring events

Updated November 17, 2025 14:00