Skip to main content
POST
cURL

Overview

Use this endpoint to request a GZip-compressed CSV export of all your Subscriptions data from OneSignal. The export includes both default and optional user data fields, and supports filters to refine the dataset. The file is downloadable via a URL returned in the API response.

How to use this API

By default, this exports all Subscriptions in the app.

Optional filters

Narrow the export using any of these body parameters:
string
Only export Subscriptions from a specific segment. Segment membership rules determine which Subscription statuses are included. Use with include_unsubscribed to include unsubscribed Subscriptions.
string
A Unix timestamp in seconds. Export Subscriptions whose last_session is after this value. Example: use 1704067200 for Subscriptions active since January 1st, 2024.
boolean
default:"false"
When exporting a segment, set to true to include unsubscribed Subscriptions alongside subscribed ones. By default, segment-filtered exports only return subscribed Subscriptions. This parameter has no effect when segment_name is not provided. See Subscription statuses for what counts as subscribed vs. unsubscribed.
string[]
Additional columns to include in the CSV. If you omit this parameter, the API defaults to external_user_id, country, and timezone_id.

Example successful response

200 OK

Export time considerations

  • Generation speed: ~2,000 records per second.
  • File readiness: The csv_file_url may return a 404 until generation completes.
  • Download retry: Poll the file URL at intervals until the file is ready.
  • File expiration: The file remains available for 3 days after generation.
  • Concurrency: Only one export per OneSignal account can run at a time. Wait until the .csv.gz file is downloaded before triggering another export.

File not ready (404 response)

While the export is generating, requests to the csv_file_url return:
Poll the URL until the file is ready. Base your retry interval on expected data volume and the ~2,000 records/second generation speed.

CSV data contents

Every export includes a set of default columns. To add optional columns, use the extra_fields parameter.

Default columns

device_type values


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.

Body

application/json
extra_fields
enum<string>[]

Additional properties that you can include in the CSV.

Available options:
external_user_id,
onesignal_id,
location,
country,
rooted,
ip,
web_auth,
web_p256,
unsubscribed_at,
notification_types,
timezone_id
last_active_since
string

A Unix timestamp (in seconds) used to filter Subscriptions based on recent activity. Only Subscriptions with a last_session timestamp after this value will be included in the export. Example: To export Subscriptions active since January 1st, 2024, use 1704067200.

segment_name
string

The name of a specific segment to filter the export. Only subscriptions that belong to this segment will be included in the CSV. Omit this field to export all subscriptions in the app.

include_unsubscribed
boolean
default:false

When used with segment_name, set to true to include unsubscribed subscriptions in the export. By default, segment-filtered exports only return subscribed subscriptions. This parameter has no effect when segment_name is not provided.

Response

200

csv_file_url
string

The URL to download the CSV file. The file is available for 3 days after generation.