Last updated Mar 5, 2025

Poll events

On This Page

    This API is designed for efficient retrieval of events in a simple, paginated manner with time-based filtering only. If you need more advanced filtering or queries, refer to the /events endpoint.

    This tutorial will help you to:

    • Transition from the /events endpoint to the new /events-stream endpoint.

    • Utilize time-based filtering for polling events.

    • Implement Bearer authentication with an API key.

    Before You Begin

    To complete this migration, you need the following:

    Authentication

    The new /events-stream endpoint requires Bearer authentication with an API key.

    Steps to Retrieve API Key

    1. Go to Atlassian Administration and select your organization.

    2. Navigate to Settings > API keys.

    3. Select Create API key.

    4. Name the API key, set an expiration date if needed, and select Create.

    5. Copy the API key and store it securely, as it won't be visible again.

    Steps to Migrate

    1. Update Endpoint Path

    Modify your API calls from /v1/orgs/{orgId}/events to the new /v1/orgs/{orgId}/events-stream path.

    1. Adjust Query Parameters

    Ensure your requests only include the following:

    • from and to for time-based filtering, using epochMillis.

    • cursor for pagination, leveraging prev/next from responses.

    • Consider using sortOrder (desc/asc) for consistent sorting.

    • Set a limit for page size, with the new default being 200.

    1. Handle Sorting Changes

    To manage changes effectively, ensure the following:

    • The new endpoint uses event processing time for sorting, instead of the time the event occurred. This is to ensure no events that are processed out of order are missed as you poll for new events.

    • Expect processedAt as a new attribute in event responses.

    1. Example Request

      1
2
      curl --request GET \
--url '<https://api.atlassian.com/admin/v1/orgs/{orgId}/events-stream'> \
--header 'Authorization: Bearer <api_key>' \
--header 'Accept: application/json'

    Improvements and Enhancements

    Cursor Handling

    • The sortOrder is maintained in the cursor and does not need to be provided through multiple pages to maintain consistent ordering.

    • A cursor is now returned on the last page of events to facilitate seamless polling.

    Default Page Size

    • The default page size for polling is increased to 200, with a maximum of 500, optimizing data retrieval.

    Conclusion

    Transitioning to the new /events-stream endpoint enhances the efficiency and reliability of polling events. Implement these changes to ensure a smooth migration and improved performance of your applications.

    For more information, refer to the API documentation.

    Rate this page: