Last modified May 20, 2020 by Gordon Glauser

Swrve Export API guide

The Swrve Export APIs enable you to export data from the Swrve service. These APIs enable the export of KPI, item sales, event count, and campaign data.
Never call the Export API from within your app. The Export API is hosted in the Swrve dashboard and not designed for high levels of traffic.

In addition to the app’s API key you must also provide a personal key to access the export APIs. For more information, see Where do I find my API Key and personal key?

This article references Swrve’s URLs for all data and content stored in both our US and EU data centers. Click the relevant tab based on your app configuration. For more information, see How do I configure the Swrve SDK for EU data storage?

KPI export

The Swrve Export API enables you to export KPI data from the Swrve service. All of the KPI data that is displayed in Swrve is available through this REST API. The data is available in JSON and HTML format. The HTML data produces a table, which is especially useful for performing Excel web queries or for import into Google Spreadsheets. To request JSON data, add .json to the end of the URL. To request HTML data, add .html.

Call all of the API calls below with HTTP GET. All of the URLs share a common root: https://dashboard.swrve.com/api/1/exporter/kpi (or https://eu-dashboard.swrve.com/api/1/exporter/kpi for EU-configured apps). To get DAU data as JSON, the URL becomes https://dashboard.swrve.com/api/1/exporter/kpi/dau.json (https://eu-dashboard.swrve.com/api/1/exporter/kpi/dau.json), and to get DAU data as HTML, the URL becomes https://dashboard.swrve.com/api/1/exporter/kpi/dau.html (https://eu-dashboard.swrve.com/api/1/exporter/kpi/dau.html).

Common URL parameters

The following parameters are used by all calls in the KPI Exporter API:

Parameter Presence Description
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.
history Required (if start is not used) This parameter is used in conjunction with the specified granularity to fetch the N last data points starting from the current date. For example, if history is set to 8 and the hour granularity is specified, then the data points of the last 8 hours are fetched.
start Required (if history is not used) The start date of the date range from which data is fetched. The following date formats are supported: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-dd-hh. All dates use the local timezone of the app.
stop Optional The end date of the date range from which data is fetched. Only set the end date if a start date is specified. The following date formats are supported: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-dd-hh. All dates use the local timezone of the app. If no end date is specified, the current time is used by default.
segment Optional The segment from which data is to be fetched. If no segment is specified, data from all users is fetched by default.
granularity Optional The temporal granularity of the fetched data. The granularities supported by each KPI are listed in the table below. The default granularity is denoted with an asterisk. The granularity 24hour_rolling is calculated over the proceeding 24 hours reported hourly. The granularity 30day_rolling is calculated over the preceding 30 days reported daily.
transpose Optional This parameter is only relevant for the .html version of this call. If set to true, the columns and rows of the generated table are switched. This parameter is set to false by default.
only_data Optional This parameter is only relevant for the .html version of this call. If set to true, the row and column headers of the generated table are removed. This parameter is set to false by default.

Extra parameters

The following parameter is only required for some API calls. The documentation for each call below specifies if these extra parameters are required.

Parameter Presence Description
currency Optional The virtual currency of interest. If no currency is specified, data is fetched from all virtual currencies.

KPIs

Name API Supported granularity
Default is marked with *
Extra parameters
DAU dau day*, 24hour_rolling
MAU mau 30day_rolling*
DAU / MAU dau_mau day*
New Users new_users hour, day*, 24hour_rolling, month, year
Daily Paying Users dpu day*, 24hour_rolling
Conversion conversion hour, day*, 24hour_rolling, month, year
Revenue dollar_revenue hour, day*, 24hour_rolling, month, year
Currency Spent currency_spent hour, day*, 24hour_rolling, month, year currency
Currency Spent / DAU currency_spent_dau day*, 24hour_rolling currency
Currency Purchased currency_purchased hour, day*, 24hour_rolling, month, year currency
Currency Purchased / DAU currency_purchased_dau day*, 24hour_rolling currency
Currency Given currency_given hour, day*, 24hour_rolling, month, year currency
Items Purchased items_purchased hour, day*, 24hour_rolling, month, year currency
Items Purchased / DAU items_purchased_dau day*, 24hour_rolling currency
Session Count session_count hour, day*, 24hour_rolling, month, year
Avg Session Length avg_session_length hour, day*, 24hour_rolling, month, year
Day N Retention day[N]_retention hour, day*, 24hour_rolling, month, year
ARPU Daily arpu_daily day*, 24hour_rolling
ARPPU Daily arppu_daily day*, 24hour_rolling
ARPU Monthly arpu_monthly 30day_rolling*
ARPPU Monthly arppu_monthly 30day_rolling*
Avg Playtime avg_playtime day*, 24hour_rolling
Day 1 Reengagement day1_reengagement hour, day*, 24hour_rolling, month, year
Day 3 Reengagement day3_reengagement hour, day*, 24hour_rolling, month, year
Day 7 Reengagement day7_reengagement hour, day*, 24hour_rolling, month, year

Examples

Get DAU for a specific time range:

US

EU

Get MAU for the last 60 days (30day_rolling granularity):

US

EU

Get Currency Spent for the coins currency in the TopPlayers segment:

US

EU

Get Avg Session Length in HTML format, transposed and without data labels:

US

EU

Get Day 1 Retention (or Day N Retention):

US

EU

Get Day7 Retention (or Day N Retention):

US

EU

Get Avg Playtime for last two days in 24hour_rolling granularity:

US

EU

Error codes

If an error occurs while processing the request, you may receive one or more of the the following error codes and need to make sure your integration is equipped to handle error conditions.

Code Text Description
400 Invalid Parameter The request included an invalid parameter, based on the specification.
404 Invalid API Key Check that your API key is correct.
429 Rate Limit Exceeded Slow down the request rate.
503 Service Unavailable An error occurred on the Swrve server side. Attempt to send the request at a later time, if possible.

Event export

The Swrve Export API enables you to export event count information from the Swrve service.

The data is available in JSON and HTML format. The HTML data produces a table, which is especially useful for performing Excel web queries or for import into Google Spreadsheets. To request JSON data, add .json to the end of the URL. To request HTML data, add .html.

Call all of the API calls below with HTTP GET. All of the URLs share a common root: https://dashboard.swrve.com/api/1/exporter/event/
(https://eu-dashboard.swrve.com/api/1/exporter/event/)

Common URL parameters

The following parameters are used by all calls in the Event Export API:

Parameter Presence Description
name Required The name of the event to be queried.
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.
history Required (if start is not used) This parameter is used in conjunction with the specified granularity to fetch the N last data points starting from the current date. For example, if history is set to 8 and the hour granularity is specified, then the data points of the last 8 hours are fetched.
start Required (if history is not used) The starting date of the date range from which data is fetched. The following date formats are supported: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-dd-hh. All dates use the local timezone of the app.
stop Optional The end date of the date range from which data is fetched. Only set the end date if a start date is specified. The following date formats are supported: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-dd-hh. All dates use the local timezone of the app. If no end date is specified, the current time is used by default.
segment Optional The segment from which data is to be fetched. If no segment is specified, data from all users is fetched by default.
granularity Optional The temporal granularity of the fetched data, set to day by default. Event export calls support month, day, and hour only.
transpose Optional This parameter is only relevant for the .html version of this call. If set to true, the columns and rows of the generated table are switched. This parameter is set to false by default.
only_data Optional This parameter is only relevant for the .html version of this call. If set to true, the row and column headers of the generated table are removed. This parameter is set to false by default.

Event count

This API call gets the event count for a named event.

URL

US

https://dashboard.swrve.com/api/1/exporter/event/count

EU

https://eu-dashboard.swrve.com/api/1/exporter/event/count

Example

US

EU

Event list

This API call gets a list of the event names that have been received by Swrve from the event API. This API should be used to enumerate a list of all event names so that they can be passed to the event count API. This API call supports the JSON and HTML formats like all other calls in the export API. The following parameters are not required: history, start, stop, segment, and granularity.

The output is a list of event names (which match the names set in the incoming event API requests), where event API could be a link to the event API.

URL

US

https://dashboard.swrve.com/api/1/exporter/event/list

EU

https://eu-dashboard.swrve.com/api/1/exporter/event/list

Example

US

EU

Payload count

This API call gets the event payload counts for a named event and payload/key pair. This method enables you to export the data buckets that are displayed on the Events Overview screen.

The only granularity supported by this function is day.

URL

US

https://dashboard.swrve.com/api/1/exporter/event/payload

EU

https://eu-dashboard.swrve.com/api/1/exporter/event/payload

Example

US

EU

Payload key list

This API call gets a list of the event payload key names that have been received by Swrve from the event API. Use this API to enumerate a list of all event payload key names so that they can be passed to the payload count API. This API supports the JSON and HTML formats like all other calls in the export API. The following parameters are not needed: history, start, stop, segment, and granularity.

The return value is a list of string names that correspond to the payload_key parameter of named events sent to Swrve using the event API.

URL

US

https://dashboard.swrve.com/api/1/exporter/event/payloads

EU

https://eu-dashboard.swrve.com/api/1/exporter/event/payloads

Example

US

EU

Error codes

See KPI Export.


User cohorts export

This API call gets the specified cohort_type data for daily cohorts for the days specified. A user cohort represents a section of users who start using the app on a particular day. You can view data for those users for the 30 days after they joined and compare this to other users starting on other days. You can get the following information for any cohort:

  • Retention – the number of retained users.
  • Avg Sessions – the average number of sessions started per retained user.
  • Avg Playtime – the average session length per retained user.
  • Avg Revenue – the average revenue generated per retained user.
  • Total Revenue – the total revenue generated.

The data is available in JSON and HTML format. The HTML data produces a table, which is especially useful for performing Excel web queries or for import into Google Spreadsheets. To request JSON data, add .json to the end of the URL. To request HTML data, add .html.

Call the API call below with HTTP GET. The URL has the root:
https://dashboard.swrve.com/api/1/exporter/cohorts/daily
(https://eu-dashboard.swrve.com/api/1/exporter/cohorts/daily)

Common URL parameters

The following parameters are used by all calls in the User Cohorts Export API:

Parameter Presence Description
cohort_type Required The type of cohort data to be returned. Must be one of retention, avg_sessions, avg_playtime, avg_revenue and total_revenue.
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.
start optional The starting day of the date range from which data is fetched in the format: yyyy-mm-dd. If no start date is specified, the last 30 days are fetched.
stop Optional (required if start is specified) The end date of the date range from which data is fetched in the format: yyyy-mm-dd.
segment Optional The segment from which data is to be fetched. If no segment is specified, data from all players is fetched by default.

Example

US

EU

Error codes

See KPI Export.


Item sales export

The Swrve Export API enables you to export item sales data from the Swrve service.

The data is available in JSON and HTML format. The HTML data produces a table, which is especially useful for performing Excel web queries or for import into Google Spreadsheets. To request JSON data, add .json to the end of the URL. To request HTML data, add .html.

Call the API calls below with HTTP GET. All of the URLs will share a common root:
https://dashboard.swrve.com/api/1/exporter/item/
(https://eu-dashboard.swrve.com/api/1/exporter/item/)

Common URL parameters

The following parameters are used by all calls in the Item Sales Export API:

Parameter Presence Description
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.
history Required (if start is not used) This parameter is used in conjunction with the specified granularity to fetch the N last data points starting from the current date. For example, if history is set to 8 and the hour granularity is specified, then the data points of the last 8 hours are fetched.
start Required (if history is not used) The starting date of the date range from which data is fetched. The following date formats are supported: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-dd-hh. All dates use the local timezone of the app.
stop Optional The end date of the date range from which data is fetched. The end date should only be set if a start date is specified. The following date formats are supported: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-dd-hh. All dates use the local timezone of the app. If no end date is specified, the current time is used by default.
segment Optional The segment from which data is to be fetched. If no segment is specified, data from all users is fetched by default.
granularity Optional The temporal granularity of the fetched data, set to day by default. Item sales export calls support year, month, and day only.
transpose Optional This parameter is only relevant for the .html version of this call. If set to true, the columns and rows of the generated table are switched. This parameter is set to false by default.
only_data Optional This parameter is only relevant for the .html version of this call. If set to true, the row and column headers of the generated table are removed. This parameter is set to false by default.

Extra parameters

The following parameters are only required for some API calls. The documentation for each call below specifies whether these extra parameters are required.

Parameter Presence Description
uid Optional The UID of the item that you want to fetch data from. If no UID or tag is specified, all items are returned.
tag Optional The tag of the items that you want to fetch data from. If no UID or tag is specified, all items are returned.
currency Optional The virtual currency of interest. If no currency is specified, data is fetched from all virtual currencies.

Item sales

This API call gets the sales data of a particular item.

URL

US

https://dashboard.swrve.com/api/1/exporter/item/sales

EU

https://eu-dashboard.swrve.com/api/1/exporter/item/sales

Extra parameters

uid, tag, currency

Example

US

EU

Item revenue

This API call gets the revenue data of a particular item.

URL

US

https://dashboard.swrve.com/api/1/exporter/item/revenue

EU

https://eu-dashboard.swrve.com/api/1/exporter/item/revenue

Extra parameters

uid, tag, currency

Example

US

EU

Item tag

This API call gets the UIDs of all items that are associated with a particular tag.

URL

US

https://dashboard.swrve.com/api/1/exporter/item/tag

EU

https://eu-dashboard.swrve.com/api/1/exporter/item/tag

Extra parameters

tag

Example

US

EU

Error codes

See KPI Export.


Segment export

The Swrve Export API enables you to export segment information from the Swrve service.

The data is available in JSON and HTML format. The HTML data produces a table, which is especially useful for performing Excel web queries or for import into Google Spreadsheets. To request JSON data, add .json to the end of the URL. To request HTML data, add .html.

Call the API call below with HTTP GET. The URL has the root:
https://dashboard.swrve.com/api/1/exporter/segment/
(https://eu-dashboard.swrve.com/api/1/exporter/segment/)

Common URL parameters

The following parameters are used by all calls in the Segment Export API:

Parameter Presence Description
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.
transpose Optional This parameter is only relevant for the .html version of this call. If set to true, the columns and rows of the generated table are switched. This parameter is set to false by default.
only_data Optional This parameter is only relevant for the .html version of this call. If set to true, the row and column headers of the generated table are removed. This parameter is set to false by default.

Segment list

This API call gets a list of the segment names that have been created for this app. This API supports the JSON and HTML formats like all other calls in the export API. The return value is a list of string names that correspond to the name parameter of segments created for this app.

URL

US

https://dashboard.swrve.com/api/1/exporter/segment/list

EU

https://eu-dashboard.swrve.com/api/1/exporter/segment/list

Example

US

EU

Error codes

See KPI Export.


User database export

The User DB Downloads screen enables you to download data sets reflecting different properties of your users. For apps with a large number of users, these data sets are further split into multiple files. The export API for user DB downloads provides a list of all the available data and schema files, enabling you to automate the download of the data sets in which you are interested. For more information about the User DB Downloads screen, see Manually downloading user DBs.

Call this API call with HTTP GET. The URL has the root:
https://dashboard.swrve.com/api/1/userdbs.json
(https://eu-dashboard.swrve.com/api/1/userdbs.json)

Common URL parameters

The following parameters are used by all calls in the User DB Export API:

Parameter Presence Description
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.

File list

This API call returns a JSON object that lists the URLs of the various data and schema files for the different data sets. This JSON takes the following format:

where:

  • DATA_URL_* is the URL of a Gzipped CSV data file.
  • SCHEMA_URL is the URL of an SQL definition file.
  • DATE is the date of the latest update.

For example, to download the custom events fired for all users, loop through the data URLs referred to in this JSON contained list:

You must append your app ID, personal key and API key to the URL of each file request. For example:

US

EU

URL

US

https://dashboard.swrve.com/api/1/userdbs.json

EU

https://eu-dashboard.swrve.com/api/1/userdbs.json

Example

US

EU

Error codes

See KPI Export.


Campaign metadata

Swrve provides two APIs for mapping tracking events for Swrve campaign touchpoints to the relevant campaign data, such as name, dashboard URL, start date, and so forth.

Depending on the channel and action type, these Swrve campaign events are logged in two formats—Generic or Custom. For more details on which channel/actions map to which format, see Campaign Event Data Schema.

Generic campaign events API

This is the API for retrieving a mapping between the tracking ID in generic campaign events and campaign metadata.

Call this API call with HTTP GET. The URL has the root: https://dashboard.swrve.com/api/1/exporter/campaign_meta_data/generic_campaign_events
(https://eu-dashboard.swrve.com/api/1/exporter/campaign_meta_data/generic_campaign_events)

Common URL parameters

The following parameters are used by all calls in the Campaign Metadata API:

Parameter Presence Description
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.

Tracking ID mapping

This returns a CSV file that maps tracking IDs in generic campaign events to campaign metadata for all campaigns that are scheduled, active, or finished.

By uploading this table into a local store, you can map tracking IDs and campaign types to appropriate contextual information in your local reports.

Each campaign may have more than one tracking ID for platforms, locales, or test variants, where applicable.

The columns in this CSV file are:

Column Description and possible values
Tracking ID Unique individual message ID used in events.
Campaign Type The channel or type of campaign, as covered by the filters on the Campaigns page:

Email, SMS, Quick Push, Push Via Api, Geo Push, Push, Other

Variant The campaign variant, if applicable. For example, A, B, C. If the campaign does not include variants, the cell will be empty.
Locale If the campaign is localized, values will include all language variants. For example, English, Spanish, French, All Languages (Default). If the campaign does not include localized variants, the cell will be empty.
Platform The platform(s) the campaign was sent to. For example, All, iOS, Android, Web, Amazon.
Schedule Type For scheduled batch campaigns (push, email, SMS), the option selected for the the time the campaign was scheduled to be sent. For example, global (same time worldwide), optimal (user’s optimal time), local (specific time in the user’s timezone).
For in-app message and Conversation campaigns, the cell will be empty.
Start Date If specified, the scheduled campaign start date. If not specified, the cell will be empty.
End Date If specified, the scheduled campaign end date. If not specified, the cell will be empty.
Earliest Delivered The date and time the first notification was sent.
Latest Delivered The date and time the most recent notification was sent.
Archived Indicates if the campaign is archived. Possible values are true, false.
Deleted Indicates if the campaign has been deleted. Possible values are true, false.
Silent Indicates if the campaign is a background update, or silent notification. Possible values are true, false
Campaign ID Parent Campaign ID, as displayed in the Swrve dashboard URL for a particular campaign.
Campaign Name Name of the campaign when created in the Swrve dashboard.
Campaign Description Description of the campaign when created in the Swrve dashboard.
Campaign URL The URL link for the campaign in the Swrve dashboard.
Campaign Status The current status of the campaign. Possible values are active, archived, draft, failed, inactive, scheduled, sending, sent.
Primary Goal Type If set during campaign creation, the type of event for your primary goal. Possible values are event, purchase (in-app purchase), valid_iap (purchase).
Primary Goal Value The event name for the primary goal. For example, flight.search.
Secondary Goal Type If set during campaign creation, the type of event for your secondary goal. Possible values are event, purchase (in-app purchase), valid_iap (purchase).
Secondary Goal Value The event name for the secondary goal. For example, flight.booked.
App ID The Swrve app ID, as encoded in the Swrve Dashboard URL.
App Name The name of the app in your Swrve dashboard.
Company Name The name of your company in the Swrve dashboard.

The filename format is: campaign-meta-data-generic-<APP_ID>-<CURRENT_DATE>-<RANDOM_STRING>.csv

where:

  • APP_ID is the Swrve app ID, as encoded in the Swrve Dashboard URL
  • CURRENT_DATE is a date/time-stamp
  • RANDOM_STRING is a random string

Example: campaign-meta-data-generic-12345-2020-03-30_14-03-07-31f44b88388852cc.csv

Custom campaign events API

This is the API for retrieving a mapping between the tracking ID in custom campaign events and campaign metadata.

Call this API call with HTTP GET. The URL has the root: https://dashboard.swrve.com/api/1/exporter/campaign_meta_data/generic_campaign_events
(https://eu-dashboard.swrve.com/api/1/exporter/campaign_meta_data/generic_campaign_events)

Common URL parameters

The following parameters are used by all calls in the Campaign Metadata API:

Parameter Presence Description
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.

Tracking event mapping

This returns a CSV file mapping custom Swrve campaign events to campaign metadata for all campaigns that are scheduled, active, or finished.

By uploading this table into a local store, you can map these event names to appropriate contextual information in your local reports.

Each campaign may have more than tracking event for platforms, locales, or test variants, where applicable.

This will return a CSV file with the following columns:

Column Description
S3 event name This is the event name as recorded in the raw AWS S3 logs.

For example, Swrve.Messages.Push-123.engaged

This event name encodes the channel (push), action (engaged), and message ID (123).

UserDB column name This is the corresponding event name as used in the Swrve Events User Database export (push and in-app messages only).

For example, swrve_messages_push-1_engaged

Action The action the user has taken, for example, engaged.
Tracking ID Unique individual message ID used with the campaign type.
Campaign Type The campaign channel, for example Conversation, InAppMessage, Push.
Variant The campaign variant, if applicable. For example, A, B, C. If the campaign does not include variants, the cell will be empty.
Locale If the campaign is localized, values will include all language variants. For example, English, Spanish, French, All Languages (Default). If the campaign does not include localized variants, the cell will be empty.
Platform The platform(s) the campaign was sent to. For example, All, iOS, Android, Web, Amazon.
Schedule Type For scheduled batch campaigns (push, email, SMS), the option selected for the the time the campaign was scheduled to be sent. For example, global (same time worldwide), optimal (user’s optimal time), local (specific time in the user’s timezone).

For in-app message and Conversation campaigns, the cell will be empty.

Start Date If specified, the scheduled campaign start date. If not specified, the cell will be empty.
End Date If specified, the scheduled campaign end date. If not specified, the cell will be empty.
Campaign ID Parent Campaign ID, as displayed in the Swrve dashboard URL for a particular campaign.
Campaign Name Name of the campaign when created in the Swrve dashboard.
Campaign Description Description of the campaign when created in the Swrve dashboard.
Campaign URL  The URL link for the campaign in the Swrve dashboard.
Campaign Status The current status of the campaign. Possible values are active, archived, draft, failed, inactive, scheduled, sending, sent.
Primary Goal Type If set during campaign creation, the type of event for your primary goal. Possible values are event, purchase (in-app purchase), valid_iap (purchase).
Primary Goal Value The event name for the primary goal. For example, flight.search.
Secondary Goal Type If set during campaign creation, the type of event for your secondary goal. Possible values are event, purchase (in-app purchase), valid_iap (purchase).
Secondary Goal Value The event name for the secondary goal. For example, flight.booked.
App ID The Swrve app ID, as encoded in the Swrve Dashboard URL.
App Name The name of the app in your Swrve dashboard.
Company Name The name of your company in the Swrve dashboard.

The filename format is: campaign-meta-data-custom-<APP_ID>-<CURRENT_DATE>-<RANDOM_STRING>.csv

where:

  • APP_ID is the ID of the app as encoded in Swrve dashboard URL
  • CURRENT_DATE is a date/time-stamp
  • RANDOM_STRING is a random string

Example: campaign-meta-data-custom-12345-2020-03-30_14-03-07-31f44b88388852cc.csv

Error codes

See KPI Export.