POST
/
notifications
/
{message_id}
/
export_events
curl --request POST \
  --url https://api.onesignal.com/notifications/{message_id}/export_events \
  --header 'Authorization: <authorization>'
{
  "csv_file_url": "<string>"
}

​
Overview

This API mirrors the Audience Activity CSV export functionality available in the OneSignal dashboard. It lets you download a full list of event records (e.g., sends, clicks, failures) for push, email, and SMS messages:

The output varies depending on the channel used by the message.

​
How to use this API

You will need the id of the message you want to export. You can retrieve this via the Create Message or View Messages APIs.

After you make this request, you will likely get a 200 OK response with a csv_file_url.

Example successful response:

200 OK
{
    "csv_file_url": "https://onesignal-data.onesignal.com/csv_exports/YOUR_APP_ID/events_audience-activity-YOUR_MESSAGE_ID-push-2024-10-21T06-49-23PMUTC.csv.gz"
}

Depending on how large the file is, the URL may 404 with the following error:

404 CSV GET
This XML file does not appear to have any style information
associated with it. The document tree is shown below.
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>

The export file is generated at ~2,000 records per second. For large audiences, the file can take several minutes. Implement retries with exponential backoff or a similar strategy.

  • The CSV download URL is valid for 3 days after creation.
  • File names contain a random UUID to prevent guessing.
  • Only one concurrent export is allowed per OneSignal account. Always download the .csv.gz file before starting a new export.

To check file availability, send a GET request to the csv_file_url. If the file is ready, it will download. If not, retry after some delay.

​
CSV data contents

The exported CSV includes the following fields:

  • external_user_id — Maps to the External ID. See Users.
  • subscription_id — Maps to the Subscription ID. See Subscriptions.
  • device_type — The platform/channel the Subscription is for.
  • sent — Timestamp of when the message was sent.
  • delivered — Timestamp of confirmed delivery. See Confirmed Delivery.
  • clicked — Timestamp of click event (if any).
  • onesignal_id — Maps to the internal OneSignal User ID.
  • failed — Timestamp of delivery failure.
  • unsubscribed — Timestamp of unsubscription event.
  • failure_message — Description of the failure, if any. See Push message reports.

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
default:YOUR_NOTIFICATION_ID
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.

Response

200
application/json

200

The response is of type object.