GET
/
notifications
/
{message_id}
?app_id=
{app_id}
View message
curl --request GET \
  --url 'https://api.onesignal.com/notifications/{message_id}?app_id={app_id}' \
  --header 'Authorization: <authorization>'
{
  "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": [
    "<any>"
  ],
  "failed": 123,
  "global_image": "<string>",
  "headings": {},
  "id": "<string>",
  "included_segments": [
    "<any>"
  ],
  "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": {}
}

Overview

The View message API allows you to fetch data from a single push, email, or SMS message at a time. If you want to get multiple messages at a time, use the View messages 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.

How to use this API

This API is most commonly used when sending Transactional messages to individual users. The response of our Create message API has an id which corresponds to the message_id used in this request. You can store this message_id on your server and (after giving your users some time to interact with the message) pull the data if desired. 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. To view outcome data for the message, you must include the outcome_name parameter with the name of the outcome you want to fetch, along with the accompanying aggregation type (.count or .sum), for example: os__click.count. For more information on outcome definitions, see View Outcomes.

Headers

Authorization
string
default:Key YOUR_APP_API_KEY
required

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

Path Parameters

message_id
string
required

The identifier of the message in UUID v4 format. Get this id in the response of your Create Message API request, the View Messages API, and in your OneSignal dashboard Message Reports.

Query Parameters

app_id
string
default:YOUR_APP_ID
required

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

outcome_names
string[]

The name and aggregation type of the outcome(s) you want to fetch. Example: my_outcome.count or my_outcome.sum. For clicks, use os__click.count. For confirmed deliveries, use os__confirmed_delivery.count. For session duration, use os__session_duration.count.

outcome_time_range
enum<string>
default:1h

Time range for the returned data. Available values: 1h (1 hour), 1d (1 day), 1mo (1 month)

Available options:
1h,
1d,
1mo
outcome_platforms
string
default:0,1,2,5,8,11,14,17

The platforms in which you want to pull the data represented as the device_type integer.

outcome_attribution
enum<string>
default:total

Attribution type for the outcomes.

Available options:
direct,
influenced,
unattributed,
total

Response

200 - application/json

200

Returns all message properties set. See the Push notifications, Email, and/or SMS Message Create APIs for all properties. Most commonly used properties for this endpoint are listed.

app_id
string

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

big_picture
string

The URL of the image set in the push notification.

canceled
boolean

Whether the message was canceled.

chrome_web_icon
string

The URL of the icon set in the push notification.

chrome_web_image
string

The URL of the image set in the push notification.

name
string

An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters.

contents
object

The main message body with language-specific values.

converted
integer

The number of times the push was clicked.

data
object

The JSON data set in the push notification if applicable.

delayed_option
string

The per-user delay option set for the message.

delivery_time_of_day
string

The delivery time of day set for the message if delayed_option is timezone.

remaining
integer

The number of messages that have not been sent yet. If null, then the system is still processing the audience, try again later.

errored
integer

The number of times the message errored.

excluded_segments
any[]

The segments excluded from the message if applicable.

failed
integer

The number of subscriptions reported unsubscribed for the message.

global_image
string

The URL of the image set in the push notification.

headings
object

The title of the push notification.

id
string

The identifier of the message in UUID v4 format.

included_segments
any[]

The segments included in the message if applicable.

ios_badgeCount
integer

The badge count set for the message if applicable.

ios_badgeType
string

The badge type set for the message if applicable.

queued_at
integer

Unix timestamp of when the message was created.

send_after
integer

Unix timestamp of when the message delivery was scheduled to begin.

completed_at
integer

Unix timestamp of when the message delivery was completed. The delivery duration from start to finish can be calculated with completed_at - send_after.

successful
integer

The number of messages successfully delivered to the push, email, or SMS servers.

received
integer

The number of messages that confirmed being received aka Confirmed Deliveries.

filters
object

The filters set for the message if applicable.

template_id
string

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

url
string

The URL of the push notification.

web_url
string

The URL of the push notification for web push subscriptions.

app_url
string

The URL of the push notification for mobile subscriptions.

platform_delivery_stats
object

The successful, errored, failed, converted, received and frequency cap counts for each platform applicable.

throttle_rate_per_minute
number

The throttle rate of the push notification if applicable.

fcap_status
string

The frequency cap status of the push notification if applicable.

outcomes
object

The id, value, and aggregation type of the outcome set in the request.