{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Events Time Range","siteUrl":"https://documentation.mailgun.com","llmstxt":{"title":"Mailgun Documentation","description":"LLMS.txt containing a map of all the documentation files for Mailgun.","sections":[{"title":"Mailgun Send Documentation","description":"All of the Mailgun Send documentation.","includeFiles":["docs/mailgun/**/*.md"],"excludeFiles":["docs/mailgun/index.md"]},{"title":"Mailgun Send OAS","description":"All of the Mailgun Send API specifications.","includeFiles":["docs/mailgun/**/mailgun.yaml"]},{"title":"Mailgun Optimize Documentation","description":"All of the Mailgun Optimize documentation.","includeFiles":["docs/inboxready/**/*.md"],"excludeFiles":["docs/inboxready/index.md"]},{"title":"Mailgun Optimize OAS","description":"All of the Mailgun Optimize API specifications","includeFiles":["docs/inboxready/**/inboxready.yaml"]},{"title":"Mailgun Validate Documentation","description":"All of the Mailgun Validate documentation.","includeFiles":["docs/validate/**/*.md"],"excludeFiles":["docs/validate/index.md"]},{"title":"Mailgun Validate OAS","description":"All of the Mailgun Validate API specifications.","includeFiles":["docs/validate/**/*.yaml"]},{"title":"Mailgun Inspect Documentation","description":"All of the Mailgun Inspect documentation.","includeFiles":["docs/inspect/**/overview.md"]},{"title":"Mailgun Inspect OAS","description":"All of the Mailgun Inspect API specifications.","includeFiles":["docs/inspect/**/*.yaml"]}]},"description":"Email events time range is a filter used to retrieve event data,helping you analyze email performance over a defined period."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"time-range","__idx":0},"children":["Time Range"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When making a request, you need to specify a time range, which consists of a starting timestamp. Additionally, you must include either an ending timestamp or indicate a search direction. If you don't provide an ending timestamp, you must specify a search direction."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you provide a range end timestamp, the relationship between the beginning and end timestamps determines the traversal direction of events—either ascending or descending. For instance, if the end timestamp is less (older) than the beginning timestamp, the result pages are returned from newer to older, and events on these pages are sorted in descending order based on their timestamps."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the end timestamp is not provided, the direction must be specified, and based on this direction, the behavior of result page traversal behaves differently:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the range is descending, then the end timestamp is determined by the user tariff plan retention period."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the range is ascending, events will continue to be recorded, however, the request time range won't be displayed on the provided pages. After retrieving the latest events and reaching an empty result page, requesting the next page URL later will show events that happened afterward. This process can continue indefinitely."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Warning!"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Although it may appear that real-time event polling can be achieved by continuously traversing the next URLs of an ascending time range without an explicit end timestamp, the process is not as straightforward as it seems. Please refer to the guidelines outlined in the Event Polling section for the correct approach."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If both the end range dates and the direction of the search are specfied, then they should agree with each other, otherwise the request will return an error."]}]},"headings":[{"value":"Time Range","id":"time-range","depth":1}],"frontmatter":{"seo":{"title":"Events Time Range","description":"Email events time range is a filter used to retrieve event data,helping you analyze email performance over a defined period."}},"lastModified":"2026-10-28T19:46:32.475Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/mailgun/user-manual/events/time-range","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}