Skip to main content
GET
/
notifications?app_id=
{app_id}
&limit=
{limit}
&offset=
{offset}
&kind=
{kind}
&template_id=
{template_id}
&time_offset=
{time_offset}
View messages
curl --request GET \
  --url 'https://api.onesignal.com/notifications?app_id={app_id}&limit={limit}&offset={offset}&kind={kind}&template_id={template_id}&time_offset={time_offset}' \
  --header 'Authorization: <authorization>'
{
  "total_count": 123,
  "time_offset": "<string>",
  "next_time_offset": 123,
  "offset": 123,
  "limit": 123,
  "notifications": [
    {
      "app_id": "<string>",
      "big_picture": "<string>",
      "canceled": true,
      "chrome_web_icon": "<string>",
      "chrome_web_image": "<string>",
      "name": "<string>",
      "contents": {
        "en": "<string>"
      },
      "converted": 123,
      "data": {},
      "delayed_option": "<string>",
      "delivery_time_of_day": "<string>",
      "remaining": 123,
      "errored": 123,
      "excluded_segments": "<array>",
      "failed": 123,
      "global_image": "<string>",
      "headings": {},
      "id": "<string>",
      "included_segments": "<array>",
      "ios_badgeCount": 123,
      "ios_badgeType": "<string>",
      "queued_at": 123,
      "send_after": 123,
      "completed_at": 123,
      "successful": 123,
      "received": 123,
      "filters": {},
      "template_id": "<string>",
      "url": "<string>",
      "web_url": "<string>",
      "app_url": "<string>",
      "platform_delivery_stats": {},
      "throttle_rate_per_minute": 123,
      "fcap_status": "<string>",
      "outcomes": {}
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The View messages API fetches data for up to 50 push, email, or SMS messages at a time. To fetch a single message, use the View message API. In most cases, use Event Streams instead. This API does not return Journey-sent messages. See Journey analytics for details. Messages sent through the API are retained for 30 days after creation; messages sent through the OneSignal dashboard are retained for the app’s lifetime. See Rate limits for details on how often you can pull your message data with this API.

​
How to use this API

Use time-offset pagination for sequential pulls of all messages, and standard pagination for ad-hoc queries. For ETL or bulk export pipelines, use Event Streams instead. Filter results to a specific message kind or template using the kind and template_id query parameters. Both filters work with either pagination style.

​
Optimized pagination with 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 — the oldest messages appear first based on the send_after date.

​
Accepted time_offset values

  • ISO 8601 formatted timestamp — for example, 2025-01-01T00:00:00.000Z (January 1, 2025, at 00:00 UTC).
  • Opaque cursor token (Base64-encoded) — provided in the API response as next_time_offset.
1

Initial fetch

To fetch messages from a specific date onward, set time_offset to an ISO 8601 formatted timestamp. For example, to retrieve messages sent since January 1, 2025: time_offset=2025-01-01T00:00:00.000Z.
  • time_offset cannot be used with the standard offset parameter.
  • time_offset excludes messages that match the exact timestamp to avoid duplicates.
  • The response includes next_time_offset, a cursor token for the next page. No decoding required. For example: "next_time_offset": "MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw=="
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==.
3

Continue until completion

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

Handling new messages

Because results are sorted ascending, new messages are added to the end. To resume fetching from where you left off, reuse the last next_time_offset that returned an empty response.

​
Standard pagination

Use the limit and offset parameters to page through notifications for an app. The maximum result size is 50, and the default limit is 50. Use limit to specify the result size and offset to increment by the limit value with each request. For example, the first request uses offset=0, the second offset=50, the third offset=100, and so on. Standard pagination is convenient for ad-hoc queries but degrades as the offset value grows. For sequential pulls of all messages, use time-offset pagination.

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key. See Keys & IDs.

Query Parameters

​
app_id
string
default:YOUR_APP_ID
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

​
limit
integer<int32>

Specifies the maximum number of messages to return in a single query. The maximum and default is 50 messages per request.

​
offset
integer<int32>

Controls the starting point for the notifications being returned. Default is 0. Results are returned and sorted in descending order by queued_at.

​
kind
integer<int32>

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.

​
template_id
string

The template ID in UUID v4 format set for the message if applicable. See Templates.

​
time_offset
string

An ISO 8601 formatted timestamp or Base64 integer token (provided in the API response). See time_offset Accepted Values.

Response

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.

​
total_count
integer

The total number of messages available in the dashboard irrespective of page

​
time_offset
string

The time_offset if specified in the request.

​
next_time_offset
integer

A Base64 integer token representing the next group of messages to fetch if time_offset provided.

​
offset
integer

The offset specified. Defaults to 0 if not provided in the request.

​
limit
integer

The limit specified. Defaults to 50 if not provided in the request.

​
notifications
object[]

An array of message objects. notifications: [] indicates no more messages to fetch. The data provided is generally the most desired from this request