View outcomes
View and export push notification outcome metrics such as clicks, conversions, and custom events.
View the details of all the outcomes associated with your app.
Overview
Use this API to retrieve Outcome metrics associated with your OneSignal app, including push notification interactions and custom-defined events. Outcomes include data points like:
- Clicks: Number of users who clicked on a push.
- Confirmed Deliveries: Number of confirmed message deliveries.
- Session Durations: Number of sessions initiated.
- Custom Events: Actions like purchases, form submissions, or any event your app tracks via custom Outcome names.
For details on configuring custom Outcomes, refer to the Outcomes documentation.
Outcomes are stored for approximately 30 days. To retain this data, you should regularly export it before it expires.
How to use this API
This API allows you to filter and aggregate Outcome data using several query parameters.
outcome_names
Specify one or more Outcome names with an aggregation type suffix (.count
or .sum
).
Default Outcome names:
os__click.count
– Push notification clicks.os__confirmed_delivery.count
– Confirmed deliveries.os__session_duration.count
– Total sessions.
Custom Outcome names:
- You can track any custom event name (e.g.
Purchase
,Signup
). - If the custom name contains a comma, include only one name per request to avoid parsing issues.
- Example:
outcome_names=os__click.count,Purchase.count
outcome_time_range
The time range values can be one of the following:
1h
= (default) the last 1 hour data.1d
= the last 1 day data.1mo
= the last 1 month data.
outcome_platforms
Maps to the subscription type property. Default is data from all platforms enabled for your OneSignal App.
device_type | type |
---|---|
0 | iOSPush |
1 | AndroidPush |
2 | FireOSPush |
5 | ChromePush |
8 | FirefoxPush |
11 | |
14 | SMS |
17 | SafariPush |
Example: outcome_platform=0
for iOS outcome_platform=17,8
for Safari and Firefox.
outcome_attribution
The way in which the Outcome occurred:
direct
= the Outcome occurred when the user interacted with the message. Some Outcomes only havedirect
attribution likeos__click
andos__confirmed_delivery
because they only occur as the direct result of the message.influenced
= the Outcome occurred within the Time Window of the message being sent, but the user never interacted with the message. See Outcomes for details.unattributed
= the Outcome occurred without a direct or influenced attribute.total
= (default) the sum of direct+influenced+unattributed.
Headers
Your App API key with prefix Key
. See Keys & IDs.
Path Parameters
Your OneSignal App ID in UUID v4 format. See Keys & IDs.
Query Parameters
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
.
Time range for the returned data. Available values: 1h
(1 hour), 1d
(1 day), 1mo
(1 month)
1h
, 1d
, 1mo
The platforms in which you want to pull the data represented as the device_type
integer.
Attribution type for the outcomes.
direct
, influenced
, unattributed
, total
Response
200
The response is of type object
.