Overview

The View messages API allows you to fetch data from up to 50 push, email, or SMS message at a time. If you want to get a single message's data, use the View message API. In most cases, you will likely want to use Event Streams instead.

Currently this API does not provide Journey-sent messages. See Journey analytics for details.

Messages sent through the API and Automated Messages are only accessible 30 days after creation; however, messages sent using the OneSignal dashboard are accessible for the app's lifetime.

See our Rate limits for details on how often you can pull your message data with this API.

---

How to use this API

Standard Pagination

Using the limit and offset parameters you can make multiple requests to page through the notifications for an app. You can pull a maximum of 50 messages at a time and with each request, use limit to specify the result size and offset to increment by the limit value each time. The defaultlimit if not specified is 50.

For example, your first request can have offset=0, second request will have offset=50, third request offset=100, etc.

Pagination queries using limit and offset are convenient but can suffer from poor latency especially as the offset value grows. Therefore standard pagination is not well suited to any ETL use cases. Consider using Event Streams instead.

Optimized Pagination - Time Offset

To efficiently retrieve all available messages for an app, use time_offset-based pagination. When time_offset is specified, the sort order changes from descending to ascending, meaning the oldest messages appear first based on the send_after date.

time_offset Accepted Values

• ISO8601 formatted timestamp – e.g., 2025-01-01T00:00:00.000Z (January 1st, 2025, at 12:00 AM UTC).
• Base64 integer token – provided in the API response.

Step 1: Initial Fetch

To fetch messages from a specific date onward, set time_offset to an ISO8601 formatted timestamp. For example, to retrieve messages sent since January 1st, 2025 - time_offset=2025-01-01T00:00:00.000Z

Important Notes:

• time_offset cannot be used with the standard offset parameter.
• It excludes messages that match the exact timestamp to avoid duplicates.
• Messages created through our API are typically retained for 30 days.
• The response includes next_time_offset, a cursor token for the next page. No decoding of the token required. For example:
  "next_time_offset": "MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw=="

Step 2: Fetch Additional Pages

Use next_time_offset from the previous response as the time_offset value in the next request. For example time_offset=MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw==

Step 3: Continue Until Completion

Repeat the requests until an empty "notifications" array is returned, indicating all messages have been fetched.

Handling New Messages

Since sorting is in ascending order, new messages are added to the end of the results. To resume fetching from where you left off, reuse the last next_time_offset that returned an empty response.

---

Response data

The properties returned will include the same properties used in the original Create message request, along with the message analytics at the time of the request.

For example, if you send a message targeting the include_aliases parameter, the response will include the aliases you set. If you send with the included_segments parameter, then the response will only provide the segments you set. When targeting segments or filters, you can use the Export audience activity CSV API to get the user event data.

The table below lists all non-customizable properties returned. Properties not listed here can be found in Push channel parameters, Email channel parameters, and SMS channel parameters, depending on the target channel.

---