Reporting API

Liftoff's Reporting API enables automated access to campaign reports with groupings and metrics of your choice. It gives your BI team direct, programmatic access to campaign data. 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.

Note: Python examples assume that you have Requests installed.

Data refresh frequency: All reports are continuously updated with a delay of several hours for certain fields. The latest full day's report will be available by 5am UTC the following day. For example, to retrieve a complete report for September 12th, 2024, please request on September 13th, 2024 at 5am or later. The max date range per request is one year. 

Quick navigation

• Getting started
• Authentication
• API structure
• Errors
• Endpoints
  • GET /reports
  • POST /reports
  • GET /reports/{ID}/status
  • GET /reports/{ID}/data
  • GET /apps
  • GET /campaigns
  • GET /creatives
  • GET /customer
  • GET /events
• Sample workflow
• What you can do with the Reporting API
• Common use cases
• Frequently asked questions

Getting started

1. Contact your Account Manager to get API key and API secret sent to you.
2. Call GET /customer to retrieve your billing timezone. Use this value in all subsequent report requests.
3. Explore the various entities associated with your account (i.e. apps, creatives, campaigns, events) via the following endpoints. You will be prompted for a password.

curl --user 'API_KEY:API_SECRET' --url https://data.liftoff.io/api/v1/apps
curl --user 'API_KEY:API_SECRET' --url https://data.liftoff.io/api/v1/creatives
curl --user 'API_KEY:API_SECRET' --url https://data.liftoff.io/api/v1/campaigns
curl --user 'API_KEY:API_SECRET' --url https://data.liftoff.io/api/v1/events

requests.get(
    "https://data.liftoff.io/api/v1/apps",
    auth=("API_KEY", "API_SECRET"),
)
requests.get(
    "https://data.liftoff.io/api/v1/creatives",
    auth=("API_KEY", "API_SECRET"),
)
requests.get(
    "https://data.liftoff.io/api/v1/campaigns",
    auth=("API_KEY", "API_SECRET"),
)
requests.get(
    "https://data.liftoff.io/api/v1/events",
    auth=("API_KEY", "API_SECRET"),
)

Create a report request and validate it with the test=true query parameter. This ensures that you don't run into rate limits while testing.

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"start_time":"2019-01-01","end_time":"2019-01-03"}' \
  --user 'API_KEY:API_SECRET' \
  --url https://data.liftoff.io/api/v1/reports?test=true

requests.post(
    "https://data.liftoff.io/api/v1/reports",
    json={
        "start_time": "2019-01-01",
        "end_time": "2019-01-03",
    },
    params={"test": "true"},
    auth=("API_KEY", "API_SECRET"),
    headers={"Content-Type": "application/json"},
)

Check that it passes without errors.

{ "message": "Validation passed without errors." }

Generate the report without the test query parameter.

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"start_time":"2019-01-01","end_time":"2019-01-03"}' \
  --user 'API_KEY:API_SECRET' \
  --url https://data.liftoff.io/api/v1/reports

requests.post(
    "https://data.liftoff.io/api/v1/reports",
    json={
        "start_time": "2019-01-01",
        "end_time": "2019-01-03",
    },
    auth=("API_KEY", "API_SECRET"),
    headers={"Content-Type": "application/json"},
)

The report response will contain a report ID if it was successfully created.

{
  "id": "abc123",
  "created_at": "2020-11-15T00:00:00Z",
  "state": "queued",
  "parameters": {
    "start_time": "2019-01-01",
    "end_time": "2019-01-03"
  }
}

The status of the report can be polled via the following:

• Recommended: Provide a callback URL with the report request. When the report is completed/failed/cancelled, a message will be sent to the provided callback URL. An OPTIONS request is made to the endpoint before report creation to verify the host is reachable.
• Poll the /reports/{ID}/status endpoint once every minute.

curl --user 'API_KEY:API_SECRET' \
  --url https://data.liftoff.io/api/v1/reports/{ID}/status

requests.get(
    "https://data.liftoff.io/api/v1/reports/{ID}/status",
    auth=("API_KEY", "API_SECRET"),
)

{
  "id": "abc123",
  "created_at": "2020-11-15T00:00:00Z",
  "state": "completed",
  "parameters": {
    "start_time": "2019-01-01",
    "end_time": "2019-01-03"
  }
}

When the report is generated, its state will be marked as "completed", and the report data can be obtained via the following:

curl --user 'API_KEY:API_SECRET' \
  --url https://data.liftoff.io/api/v1/reports/{ID}/data

requests.get(
    "https://data.liftoff.io/api/v1/reports/{ID}/data",
    auth=("API_KEY", "API_SECRET"),
)

Authentication

Liftoff's Reporting API supports HTTP basic authentication.

curl --request GET \
  --user 'API_KEY:API_SECRET' \
  --url https://data.liftoff.io/api/v1/reports

requests.get(
    "https://data.liftoff.io/api/v1/reports",
    auth=("API_KEY", "API_SECRET"),
)

API structure

All API URLs start with https://data.liftoff.io/api/v1. Different endpoints can be called by appending to the base url. All available end points are described in the table below:

Rate limits

All valid endpoints are rate-limited and will return the following headers:

• x-rate-limit-max
• x-rate-limit-remaining

Errors

The following errors can be returned by the API:

• 400 "BAD REQUEST"
• 403 "ACCESS DENIED"
• 404 "NOT FOUND"
• 429 "TOO MANY REQUESTS"
• 500 "INTERNAL ERROR"

Error Format:

Sample Error:

{
  "error_type": "BAD REQUEST",
  "message": "Please correct the following issues with the request.",
  "errors": [
    "start_time should be before end_time.",
    "Max allowable date range is one year."
  ]
}

Endpoints

GET /reports

This endpoint allows you to look up metadata for recently submitted reports.

curl --user 'API_KEY:API_SECRET' --url https://data.liftoff.io/api/v1/reports

requests.get(
    "https://data.liftoff.io/api/v1/reports",
    auth=("API_KEY", "API_SECRET"),
)

Response Format:

Sample Response:

[
  {
    "id": "abc123",
    "created_at": "2021-11-15T00:00:00Z",
    "state": "completed",
    "parameters": {
      "start_time": "2021-10-01",
      "end_time": "2021-11-01"
    }
  }
]

POST /reports

This endpoint allows you to generate a report. When the test query parameter is set, no report is generated, but the request will still get validated. This also has a separate rate-limit compared to requests without the query parameter.

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"group_by":["apps","campaigns"],"start_time":"2020-10-01","end_time":"2020-11-01"}' \
  --user 'API_KEY:API_SECRET' \
  --url https://data.liftoff.io/api/v1/reports

requests.post(
    "https://data.liftoff.io/api/v1/reports",
    json={
        "group_by": ["apps", "campaigns"],
        "start_time": "2020-10-01",
        "end_time": "2020-11-01",
    },
    auth=("API_KEY", "API_SECRET"),
    headers={"Content-Type": "application/json"},
)

Request Format:

Available Group By Presets:

• ["apps" "campaigns"]
• ["apps" "campaigns" "ad_format"]
• ["apps" "campaigns" "country"]
• ["apps" "campaigns" "country" "publisher"]
• ["apps" "campaigns" "creatives"]
• ["apps" "campaigns" "creatives" "country"]
• ["apps" "campaigns" "creatives" "country" "publisher"]
• ["apps" "campaigns" "creatives" "is_interstitial"]
• ["apps" "campaigns" "creatives" "publisher"]
• ["apps" "campaigns" "creatives" "publisher" "is_interstitial"]
• ["apps" "campaigns" "is_interstitial"]
• ["apps" "campaigns" "publisher"]
• ["apps" "campaigns" "publisher" "is_interstitial"]

Sample request body:

{
  "app_ids": ["abc456", "abc123"],
  "cohort_window": 1,
  "group_by": ["apps", "campaigns", "creatives"]
}

Sample response:

{
  "id": "abc123",
  "created_at": "2021-11-15T00:00:00Z",
  "state": "queued",
  "parameters": {
    "group_by": ["apps", "campaigns"],
    "start_time": "2021-10-01",
    "end_time": "2021-11-01"
  }
}

GET /reports/{ID}/status

This endpoint allows you to fetch the status of a single report. Similar to /reports endpoint but with a higher rate limit.

curl --user 'API_KEY:API_SECRET' https://data.liftoff.io/api/v1/reports/{ID}/status

requests.get(
    "https://data.liftoff.io/api/v1/reports/{ID}/status",
    auth=("API_KEY", "API_SECRET"),
)

Sample Response:

{
  "id": "abc123",
  "created_at": "2021-11-15T00:00:00Z",
  "state": "failed",
  "parameters": {
    "group_by": ["apps", "campaigns"],
    "start_time": "2021-10-01",
    "end_time": "2021-11-01"
  }
}

GET /reports/{ID}/data

This endpoint allows you to download the completed report. The report can either be JSON/CSV depending on the format provided at report creation.

curl --user 'API_KEY:API_SECRET' \
  --url https://data.liftoff.io/api/v1/reports/{ID}/data

requests.get(
    "https://data.liftoff.io/api/v1/reports/{ID}/data",
    auth=("API_KEY", "API_SECRET"),
)

Report row format:

Sample response:

{
  "columns": ["date", "app_id", "campaign_id", "spend", "impressions", "..."],
  "rows": [
     ["2019-02-08", "abc123", "zxy123", 123.12, 12, "..."]
  ]
}

GET /apps

This endpoint allows you to fetch app details.

curl --user 'API_KEY:API_SECRET' \
  --url https://data.liftoff.io/api/v1/apps

requests.get(
    "https://data.liftoff.io/api/v1/apps",
    auth=("API_KEY", "API_SECRET"),
)

Response format:

Sample response:

[
  {
    "id": "abc123",
    "name": "Sample",
    "app_store_id": "io.liftoff.sample",
    "bundle_id": "io.liftoff.sample",
    "title": "Sample",
    "platform": "Android",
    "optimization_event": {
      "id": "xyz123",
      "name": "Tutorial"
    },
    "state": "enabled"
  }
]

GET /campaigns

This endpoint allows you to fetch campaign details.

curl --user 'API_KEY:API_SECRET' \
  --url https://data.liftoff.io/api/v1/campaigns

requests.get(
    "https://data.liftoff.io/api/v1/campaigns",
    auth=("API_KEY", "API_SECRET"),
)

Response format:

Sample response:

[
  {
    "id": "fff123",
    "app_id": "abc123",
    "name": "App - iOS - JP",
    "campaign_type": "user-acquisition",
    "tracker_type": "SKAN",
    "min_os_version": "14.5",
    "max_os_version": null,
    "state": "enabled",
    "state_last_changed_at": "2021-10-01T00:00:00Z",
    "demand_product": "accelerate",
    "campaign_model": "CPI",
    "targeted_language_codes": ["en", "jp"]
  }
]

GET /creatives

This endpoint allows you to fetch creative details.

curl --user 'API_KEY:API_SECRET' \
  --url https://data.liftoff.io/api/v1/creatives

requests.get(
    "https://data.liftoff.io/api/v1/creatives",
    auth=("API_KEY", "API_SECRET"),
)

Response format:

Sample response:

[
  {
    "id": "zzz123",
    "name": "320x480_sample_html",
    "width": 320,
    "height": 480,
    "preview_url": null,
    "full_html_preview_url": null,
    "creative_type": "html",
    "created_at": "2021-10-01T00:00:00Z",
    "state": "enabled",
    "video_duration": 16,
    "video_url": "https://cdn.liftoff.io/customers/1234abcd/videos/originals/1234.mp4"
  }
]

GET /customer

This endpoint allows you to fetch customer details.

curl --user 'API_KEY:API_SECRET' \
  --url https://data.liftoff.io/api/v1/customer

requests.get(
    "https://data.liftoff.io/api/v1/customer",
    auth=("API_KEY", "API_SECRET"),
)

Response format:

Sample response:

[
  {
    "id": "xyz123",
    "company": "Liftoff",
    "timezone": "US/Pacific"
  }
]

GET /events

This endpoint allows you to fetch event details.

curl --user 'API_KEY:API_SECRET' \
  --url https://data.liftoff.io/api/v1/events

requests.get(
    "https://data.liftoff.io/api/v1/events",
    auth=("API_KEY", "API_SECRET"),
)

Response format:

Sample response:

[
  {
    "id": "xyz123",
    "app_id": "abc123",
    "name": "Tutorial"
  }
]

Sample workflow

The following is a sample Python script for requesting and downloading reports.

import requests
import time
api_key = "API_KEY"
api_secret = "API_SECRET"

# Submit request to generate a new report.
report_response = requests.post(
    "https://data.liftoff.io/api/v1/reports",
    json={
        "start_time": "2022-01-01",
        "end_time": "2022-02-01",
    },
    auth=(api_key, api_secret),
    headers={"Content-Type": "application/json"},
)
report_id = report_response.json()["id"]
print(f"Report requested. ID: {report_id}")

# Poll for report status until in a finished state.
state = ""
while state not in {"completed", "failed", "cancelled"}:
    print("Waiting 30 seconds to check status...")
    time.sleep(30)
    status_response = requests.get(
        f"https://data.liftoff.io/api/v1/reports/{report_id}/status",
        auth=(api_key, api_secret),
    )
    state = status_response.json()["state"]
    print(f"Current state: {state}")
    
# Download the completed report.
if state == "completed":
    data_response = requests.get(
        f"https://data.liftoff.io/api/v1/reports/{report_id}/data",
        auth=(api_key, api_secret),
    )
    data_response.raise_for_status()
    # Handle your raw report data here.
    with open("report_response.csv", "w") as f:
        f.write(data_response.text)
    print("Report downloaded successfully!")

What you can do with the Reporting API

Available dimensions

Reports are grouped by one of 13 fixed presets built from the following dimensions (see Group By Presets below for the full list):

• App
• Campaign
• Creative
• Country
• Publisher App
• Ad Format
• Interstitial (Y/N)

Every report automatically includes a daily date column - no need to specify it in your group_by.

You can also filter by demand product (Accelerate or Direct) or include a demand_product column (campaigns group_by only).

Creative-level spend: include creatives in your group_by to answer "which creative is spending the most?".

Available metrics

Core funnel metrics - returned in every report:

• Spend
• Impressions, Clicks, Installs
• CPM, CPC, CTR, CPI, CPA
• In-app events (any events configured on your account)

Optional metrics - enabled per request:

• Customer Revenue: total revenue across all events, plus revenue broken out per event. Set include_customer_revenue: true.
• SKAN Installs: reported separately as installs with or without a conversion value. Enable via the corresponding request flags.
• Video milestones: Starts, 25% / 50% / 75% plays, and Completes for VAST impressions. Set video_play_milestones: true. Requires your group_by to include at least one of creatives, ad_format, or country — cannot be combined with publisher or is_interstitial.

Cohort analysis

Use cohort_window to count in-app events relative to install date, from D1 up to D90. This lets you run day-level performance analysis (e.g. D7 ROAS, D30 event rates) in a single report pull. Cohort reports are limited to a 90-day date range.

• ROAS: Set include_customer_revenue: true alongside your cohort_window. The API returns revenue values; divide by spend in your BI tool to calculate ROAS.
• Retention: Only available if session or login events are configured as postbacks to Liftoff. Please check with your AM. 

Timezone alignment

Call GET /customer to retrieve your billing timezone. Use this value in all report requests so your data aligns with your Liftoff dashboard and invoices.

Common use cases