View the details for a collection of messages.
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 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.
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.
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 ValuesInitial 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
ISO8601 formatted timestamp
Important Notes:
time_offset
cannot be used with the standard offset
parameter.next_time_offset
, a cursor token for the next page. No decoding of the token required. For example: "next_time_offset": "MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw=="
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==
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.
Your App API key with prefix Key
. See Keys & IDs.
Your OneSignal App ID in UUID v4 format. See Keys & IDs.
Specifies the maximum number of messages to return in a single query. The maximum and default is 50 messages per request.
Controls the starting point for the notifications being returned. Default is 0. Results are returned and sorted in descending order by queued_at
.
Specifies which push notifications to return based on how it was created. Use this to segment push by their creation method, allowing for targeted analysis or management of notification types. All push types are returned by default. 0
- Notifications created through the dashboard. 1
- Notifications sent via API calls. 3
- Notifications triggered through automated systems.
An ISO 8601 formatted timestamp or Base64 integer token (provided in the API response). See time_offset
Accepted Values.
200
Returns all message properties for up to 50 messages per request. See the Push notifications, Email, and/or SMS Message Create APIs for all properties. Most commonly used properties for this endpoint are listed.
View the details for a collection of messages.
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 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.
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.
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 ValuesInitial 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
ISO8601 formatted timestamp
Important Notes:
time_offset
cannot be used with the standard offset
parameter.next_time_offset
, a cursor token for the next page. No decoding of the token required. For example: "next_time_offset": "MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw=="
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==
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.
Your App API key with prefix Key
. See Keys & IDs.
Your OneSignal App ID in UUID v4 format. See Keys & IDs.
Specifies the maximum number of messages to return in a single query. The maximum and default is 50 messages per request.
Controls the starting point for the notifications being returned. Default is 0. Results are returned and sorted in descending order by queued_at
.
Specifies which push notifications to return based on how it was created. Use this to segment push by their creation method, allowing for targeted analysis or management of notification types. All push types are returned by default. 0
- Notifications created through the dashboard. 1
- Notifications sent via API calls. 3
- Notifications triggered through automated systems.
An ISO 8601 formatted timestamp or Base64 integer token (provided in the API response). See time_offset
Accepted Values.
200
Returns all message properties for up to 50 messages per request. See the Push notifications, Email, and/or SMS Message Create APIs for all properties. Most commonly used properties for this endpoint are listed.