Liftoff’s reporting API enables automated access to campaign reports with groupings and metrics of your choice. Discover insights on campaign performance by analyzing funnel metrics: impressions, clicks, installs and in-app events across different groupings (e.g. country, publisher app, ad format, creatives, etc). Perform cohort analysis through the API by specifying the look-back window relative to the install.
curl --user 'username' 'https://data.liftoff.io/api/v1/apps' |
curl --header "Content-Type: application/json" \ |
{"message":"Validation passed without errors."} |
curl --header "Content-Type: application/json" \ |
{ |
curl --user 'username' |
{ |
curl --user 'username' 'https://data.liftoff.io/api/v1/reports/abc123/data' |
Liftoff’s reporting API supports HTTP Basic authentication. Here’s a quick example curl:
curl --request GET \ |
All API URLs start with “https://data.liftoff.io/api/v1”. Different end-points can be called by appending to the base url. All available end points are described in the table below:
Endpoints | HTTP Request Method | Usage Description |
GET | Look up metadata around recently submitted reports | |
POST | Generate a report | |
GET | Get the status of the report | |
GET | Download the report in CSV or JSON | |
Entity type = apps, ad_units | GET | Get information around particular entities (e.g. apps, ad units) |
All endpoints are rate-limited:
Note: responses to any rate-limited endpoints will have x-rate-limit-max and x-rate-limit-remaining headers
Name | Type | Description |
id | String | ID of the report |
created_at | Timestamp (string) | UTC timestamp. |
parameters | Report Parameters (object) | JSON body posted during initial request populated with defaults. |
state | String | Queued, cancelled, completed, failed. |
Sample curl
curl --user 'username' 'https://data.liftoff.io/api/v1/reports' |
Sample response header
... content-type: application/json;charset=utf-8 |
Sample response body
[ |
Name | Type | Description | When value is not specified |
app_ids | Array of strings (nullable) | Filters the report to only app external_ids provided | All app_ids belonging to the account |
campaign_ids | Array of strings (nullable) | Filters the report to only campaign external_ids provided. | All campaign_ids belonging to the account |
event_ids | Array of Strings (nullable) | All events belonging to the account | Filters for the app event selected for optimization |
start_time | Timestamp (string) | ISO date and time in UTC, or ISO date (with time at start of day for given timezone). | Throws an exception (400), since this is a required parameter |
end_time | Timestamp (string) | ISO date and time in UTC, or ISO date (with time at start of day for given timezone). | Throws an exception (400), since this is a required parameter |
group_by | Array of preset string combinations | Group metrics by the following combinations of entities:
| [apps, campaigns] |
cohort_window | Integer (1 - 90) (nullable) | Number of days since install. If this is specified, events will be counted since the day of install | Null |
format | String (nullable) | Output format of the report. Either CSV or JSON | CSV |
callback_url | String (nullable) | Specify an endpoint to receive a status message of the report | Null |
timezone | String (nullable) | Specify a TZ database name to use for date groupings. | UTC |
include_repeat_events | Boolean (nullable) | When enabled, all instances of post-install events will be counted, instead of just first occurrences. | true |
remove_zero_rows | Boolean (nullable) | When enabled, all rows whose numeric metrics are equal to 0 will be excluded from output. | false |
use_two_letter_country | Boolean (nullable) | When enabled, reports will use the two letter country code (as opposed to the default three letter code). | false |
Sample request body
{ |
Response:
Name | Type | Description |
id | String | ID of the report |
created_at | Timestamp (string) | UTC timestamp of report generation |
parameters | Report Parameters (object) | JSON body posted during initial request |
state | String | queued, cancelled, completed, failed |
Sample curl
curl --header "Content-Type: application/json" \ |
Sample response: header
... content-type: application/json;charset=utf-8 |
Sample response: body
{ |
Name | Type | Description |
error_type | string | Error type (i.e. “BAD REQUEST”) |
message | string | General message on possible error cause. |
errors | Array of Strings (Nullable) | List of issues with request |
Sample error: body
{ |
This endpoint allows you to get the status of the report.
Sample curl
curl --user 'username' 'https://data.liftoff.io/api/v1/reports/abc123/status' |
Sample response
{ |
This endpoint allows you to download the report
Name | Type | Description |
date | Date | yyyy-MM-dd (in UTC timezone) |
app_id | String | ID of the app that is being advertised |
campaign_id | String | ID of the advertising campaign |
creative_id | String | ID of the creative |
country_code | String (nullable) | 2 letter country-code of countries in which the ad is being shown. Only available if group by (apps, campaigns, country) is selected |
publisher_app_store_id | String (nullable) | Bundle IDs of the publisher app |
publisher_name | String (nullable) | Display name of the publisher app |
ad_format | String (nullable) | Format of the ad unit |
spend | Float | Amount of budget that was spent in that time period |
impressions | Integer | Ad impressions shown |
clicks | Integer | Number of clicks on the ads |
installs | Integer | Number of installs resulting from the ads |
<event_name> | Integer | Number of events resulting from the ads. Note that an event has to be specified. |
cpm | Float | Cost per thousand impressions. Cost is defined as ad spend. |
cpc | Float | Cost per click. Cost is defined as ad spend. |
ctr | Float | Click through rate. Cost is defined as ad spend. |
cpi | Float | Cost per install. Cost is defined as ad spend. |
cpa | Float | Cost per action. Cost is defined as ad spend. Action refers to in-app events. |
Sample response (JSON)
{ |
Sample response (CSV)
date, app_id, campaign_id, spend, impressions, clicks, installs, cpm, cpc, ctr, cpi, cpa, Tutorial (event), Login (event) |
Name | Type | Description |
error_type | string | Error type (i.e. “BAD REQUEST”) |
message | string | General message on possible error cause. |
Sample error (body)
{ "error_type": "NOT FOUND", |
This endpoint allows you to query the metadata around relevant entities (apps, campaigns, creatives, events)
Name | Type | Description |
id | String | ID of the app that is being advertised |
name | String | App title |
app_store_id | String | Apple/Play store app ID |
bundle_id | String | App bundle/package ID |
title | String | App title (as appears in creatives) |
platform | String | iOS or Android |
optimization_event | Event (nullable) | Event selected for ML optimization |
Sample curl
curl --user 'username' 'https://data.liftoff.io/api/v1/apps' |
Sample response body
[ |
Name | Type | Description |
id | String | ID of the advertising campaign |
app_id | String | ID of the app |
name | String | Name of the advertising campaign |
campaign_type | String | Type of campaign ("user-acquisition" or "reengagement") |
tracker_type | String | Type of campaign tracker ("MMP", "SKAN", or "NONE") |
min_os_version | String (nullable) | Minimum OS version of the campaign |
max_os_version | String (nullable) | Maximum OS version of the campaign |
Sample curl
curl --user 'username' 'https://data.liftoff.io/api/v1/campaigns' |
Sample response body
[ "tracker_type": "SKAN", "min_os_version": "14.5", "max_os_version": null |
Name | Type | Description |
id | String | ID of the ad creative |
name | String (nullable) | Name of the ad creative |
preview_url | String (nullable) | URL to preview the creative |
width | Integer (nullable) | Width of the creative, in pixels |
height | Integer (nullable) | Height of the creative, in pixels |
creative_type | String | The technology used to render the creative: native, native_video, html, vast |
Sample curl
curl --user 'username' 'https://data.liftoff.io/api/v1/creatives' |
Sample response body
[ |
Name | Type | Description |
id | String | ID of the in-app event |
app_id | String | ID of the advertising app |
name | String | Name of the event |
Sample curl
curl --user 'username' 'https://data.liftoff.io/api/v1/events' |
Sample response body
[ |