• API Reference

Retention Report

The Retention Report shows how many users returned to the app a certain number of days after installing the app or opening the app through a deep link.

You can identify the channels and campaigns that attract the most active app users. The retention data can be used for campaign optimization and ad billings.

Additionally, there are no rate limits, allowing you to generate reports as needed.

Request Report

POST

https://api.airbridge.io/reports/api/v5/apps/{app_name}/retention/query

Request a Retention Report.

rate limit: There is no specific limit for normal usage. However, if excessive requests that may threaten service stability are detected, a temporary 429 Too Many Requests response may be returned.

Request

Headers

Accept-Language
string

You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.

Content-Type
string

Represents the media type of the resource. Defaults to application/json.

Authorization
string

The key value to use for API requests. Instructions for getting API keys are in "how to generate API Keys".

Path Params

app_name
Requiredstring

Airbridge App Name. (Unique ID)

Body Params

from
Requiredstring

The start date of the report data to request.

  • The date must be in the format 'YYYY-MM-DD'

  • This date must correspond with the timezone set in the Airbridge app. 

  • Future dates are not permitted.

to
Requiredstring

The end date of the report data to request.

  • The date must be in the format 'YYYY-MM-DD'

  • This date must correspond with the timezone set in the Airbridge app.

  • The system only accepts dates up the current date. The time period available for querying is up to 92 days.

granularity
Requiredenum

The analytics interval period.

ENUM VALUES
day

Analyze the data by day.

week

Analyze the data by week. Calculated in 7 day intervals from the start date.

month

Analyze the data by month. Calculated the same month from the start date until the corresponding date in the subsequent month. For example, given a start date of March 10, the same month would be pretended until April 10.

hour

Analyze the data by hour. You can only set Install (App) as the start event when you set the granularity to hourly.

minute

Analyze the data by minute. You can only set Install (App) as the start event when you set the granularity to minutely.

intervalsPeriod
integer

The maximum number of intervals, or time ranges, by granularity.

  • If the granularity is day, week, or month, the default value is 30, 11, or 5, respectively.

  • If the granularity is day, week, or month, the maximum value is 120, 52, or 36, respectively. The minimum values are all 0.

  • If the granularity is hour or minute, the value is fixed to 60 and 24, respectively.

  • The result includes a “0th” interval.

startEvents
Requiredenum[]

The event that initiates a User Journey in the time period set. Choose at least 1 event.

ENUM VALUES
app_installs

Installs (App). Install events that occurred within the selected time period.

app_deeplink_opens

Deeplink Opens (App). Deeplink Open events that occurred within the selected time period.

app_deeplink_pageviews

Deeplink Pageviews (App). Deeplink Pageview events that occurred within the selected time period.

app_sign_up

Sign-up (App). Sign-up events that occurred within the selected time period.

app_sign_in

Sign-in (App). Sign-in events that occurred within the selected time period.

app_order_complete

Order Complete (App). Order Complete events that occurred within the selected time period.

returnEvents
Requiredenum[]

An in-app event performed by the user after performing a Start Event.

It is possible to set up multiple return events.

ENUM VALUES
app_order_complete

Order Complete (App). Order Complete event performed within the selected time period.

app_first_order_complete

First Order Complete (App). First Order Complete event performed within the selected time period.

app_ad_impression

Ad Impression (App). Ad Impression event performed within the selected time period.

app_ad_click

Ad Click (App). Ad Click event performed within the selected time period.

app_subscribe

Subscribe (App). Subscribe event performed within the selected time period.

measurementOption
Requiredenum

The option to view the retention by unique users or by user journeys that are separated by Start Events. [Reference]

ENUM VALUES
general_retention

General. A User Journey of a unique user is initiated by the Start Event performed by that user.

confined_retention

Confined. A User Journey of a unique user is initiated by the Start Event performed by that user. The Airbridge Device ID is used to identify unique users.

groupBy
Requiredobject

Allows you to set a group by to divide the numbers for the metric you want to see.

filters
Requiredobject[]

The filter for providing 'group by' items.

sorts
Requiredobject[]

Sort report data by 'Group By' or 'Metric'.

keyword
string
pagination
object
Request
curl -X POST 'https://api.airbridge.io/reports/api/v5/apps/{app_name}/retention/query' \ -H 'Accept-Language: ko' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}' \ -d '{"from":"2022-11-04","to":"2022-11-11","granularity":"day","intervalsPeriod":30,"startEvents":["app_installs"],"returnEvents":["app_order_complete"],"measurementOption":"general_retention","groupBy":{"fields":["channel"]},"filters":[{"field":"campaign","filterType":"IN","values":["App"]}],"sorts":[{"fieldName":"event_type","isAscending":true}],"pagination":{"skip":0,"size":50}}'
Payload
{ "from": "2022-11-04", "to": "2022-11-11", "granularity": "day", "intervalsPeriod": 30, "startEvents": [ "app_installs" ], "returnEvents": [ "app_order_complete" ], "measurementOption": "general_retention", "groupBy": { "fields": [ "channel" ] }, "filters": [ { "field": "campaign", "filterType": "IN", "values": [ "App" ] } ], "sorts": [ { "fieldName": "event_type", "isAscending": true } ], "pagination": { "skip": 0, "size": 50 }}

Response

200SUCCESS

400ERROR

Response
{ "data": { "taskId": "5e286bd4-b4b1-4c04-8f6a-123456789abc" }}
Response
{ "type": "about:blank", "title": "Bad Request", "status": 400, "traceId": "1-000000-000000000000000"}

Get Report

GET

https://api.airbridge.io/reports/api/v5/apps/{app_name}/retention/query/{task_id}

Request status

The status of an asynchronous request can be checked with task.status in the API request result.

Request

Headers

Accept-Language
string

You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.

Content-Type
string

Represents the media type of the resource. Defaults to application/json.

Authorization
string

The key value to use for API requests. Instructions for getting API keys are in "how to generate API Keys".

Path Params

app_name
Requiredstring

Airbridge App Name. (Unique ID)

task_id
Requiredstring

The task_id returned by the result of the 'Request Report' API.

Query Params

skip
number

The number of rows to be skipped.

Get results except the first N number of rows.

The default is 0.

size
number

A limit on the number of rows to be returned.

Get results of the next N rows after those skipped by the skip option.

The default is 10000.

e.g.) ?skip=200&size=100

In this case, it returns the rows 201 to 300. (skips first 200 rows, gets next 100 rows)

Request
curl -X GET 'https://api.airbridge.io/reports/api/v5/apps/{app_name}/retention/query/{task_id}?skip=0&size=10000' \ -H 'Accept-Language: ko' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'

Response

200SUCCESS

200SUCCESS

404ERROR

Response
{ "task": { "status": "RUNNING", "taskId": "5e286bd4-b4b1-4c04-8f6a-670dc7ce637d", "endedAt": "2022-01-17T19:10:00.286939+09:00" }}
Response
{ "task": { "status": "SUCCESS", "taskId": "5e286bd4-b4b1-4c04-8f6a-670dc7ce637d", "endedAt": "2022-01-17T19:10:00.286939+09:00" }, "retention": { "data": { "rows": [ { "rows": [ { "date": "2022-01-10T00:00:00+09:00/2022-01-11T00:00:00+09:00", "values": [ { "value": 0, "isMasked": true } ], "totalValue": { "value": 0, "isMasked": true } } ], "total": { "values": [ { "value": 0, "isMasked": true } ], "totalValue": { "value": 0, "isMasked": true } }, "metadata": [ "string" ] } ] }, "metadata": { "totalCount": 0 } }, "pagination": { "hasNext": false }, "notification": [ { "code": "AGG_DATA_MASKING_BY_FACEBOOK", "type": "info", "message": "some data is masked by facebook privacy policy." } ]}
Response
{ "type": "about:blank", "title": "Not Found", "status": 404, "traceId": "1-000000-000000000000000"}

Get Metadata (Event)

GET

https://api.airbridge.io/dataspec/v1/apps/{app_name}/retention-report/events

Gets a list of available report events.[Note]

Request

Headers

Accept-Language
string

You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.

Content-Type
string

Represents the media type of the resource. Defaults to application/json.

Authorization
string

The key value to use for API requests. Instructions for getting API keys are in "how to generate API Keys".

Path Params

app_name
Requiredstring

Airbridge App Name. (Unique ID)

Request
curl -X GET 'https://api.airbridge.io/dataspec/v1/apps/{app_name}/retention-report/events' \ -H 'Accept-Language: ko' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'

Response

200SUCCESS

404ERROR

There is an error in the field provided, or there is no such resource.

Response
{ "data": [ { "name": "Return Event", "events": [ { "subGroup": "Any Event", "key": "any_event", "name": "Any Event (App)", "description": "All occurred events from users who performed a Start Event within a specified period" }, { "subGroup": "App Standard Event", "key": "app_install", "name": "Install (App)", "description": "Install events from users who performed a Start Event within a specified period" } ] }, { "name": "Start Event", "events": [ { "subGroup": "", "key": "app_installs", "name": "Install (App)", "description": "Users who Installed within a specified period (Unique Install" }, { "subGroup": "", "key": "app_deeplink_opens", "name": "Deeplink Open (App)", "description": "Users who opened App via Deeplink within a specified period (Unique Deeplink Open)" } ] } ]}
Response
{ "type": "about:blank", "title": "Not Found", "status": 404, "traceId": "1-000000-000000000000000"}

Get Metadata (GroupBy)

GET

https://api.airbridge.io/dataspec/v1/apps/{app_name}/retention-report/groupbys

Gets a list of available report groupbys. [Note]

Request

Headers

Accept-Language
string

You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.

Content-Type
string

Represents the media type of the resource. Defaults to application/json.

Authorization
string

The key value to use for API requests. Instructions for getting API keys are in "how to generate API Keys".

Path Params

app_name
Requiredstring

Airbridge App Name. (Unique ID)

Request
curl -X GET 'https://api.airbridge.io/dataspec/v1/apps/{app_name}/retention-report/groupbys' \ -H 'Accept-Language: ko' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'

Response

200SUCCESS

404ERROR

There is an error in the field provided, or there is no such resource.

Response
{ "data": [ { "name": "Event Details", "fields": [ { "key": "is_first_event_per_user_id", "name": "Is First Event per User ID", "description": "Boolean type data to show whether the event has happened in the past. (per user id)\n- true: First Event. \n- false: Not the First Event\n\n(Both Web/App Event Available)", "example": "true", "isFilter": true, "type": "boolean" }, { "key": "is_first_event_per_device_id", "name": "Is First Event per Device ID", "description": "Boolean type data to show whether the event has happened in the past. (per airbridge device id)\n- true: First Event. \n- false: Not the First Event\n\n(App Event Available Only)", "example": "true", "isFilter": true, "type": "boolean" } ] }, { "name": "Touchpoint", "fields": [ { "key": "channel", "name": "Channel", "description": "The media source of the touchpoint.", "example": "moloco", "isFilter": true, "type": "string" }, { "key": "campaign", "name": "Campaign", "description": "The campaign that generated the touchpoint. The campaign name entered in SAN or collected by the campaign parameter of the tracking link.", "example": "2018_summer_campaign", "isFilter": true, "type": "string" } ] } ]}
Response
{ "type": "about:blank", "title": "Not Found", "status": 404, "traceId": "1-000000-000000000000000"}

Get Metadata (Retention Types)

GET

https://api.airbridge.io/dataspec/v1/apps/{app_name}/retention-report/retention-types

Gets a list of available report retention types. [Note]

Request

Headers

Accept-Language
string

You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.

Content-Type
string

Represents the media type of the resource. Defaults to application/json.

Authorization
string

The key value to use for API requests. Instructions for getting API keys are in "how to generate API Keys".

Path Params

app_name
Requiredstring

Airbridge App Name. (Unique ID)

Request
curl -X GET 'https://api.airbridge.io/dataspec/v1/apps/{app_name}/retention-report/retention-types' \ -H 'Accept-Language: ko' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'

Response

200SUCCESS

404ERROR

There is an error in the field provided, or there is no such resource.

Response
{ "data": [ { "key": "return_on", "name": "Return On", "description": "<img src=\"https://static.airbridge.io/images/resources/tooltip_return_on_en.png\">" }, { "key": "return_on_or_after", "name": "Return On or After", "description": "<img src=\"https://static.airbridge.io/images/resources/tooltip_return_on_or_after_en.png\">" } ]}
Response
{ "type": "about:blank", "title": "Not Found", "status": 404, "traceId": "1-000000-000000000000000"}

Get Metadata (Measurement Options)

GET

https://api.airbridge.io/dataspec/v1/apps/{app_name}/retention-report/measurement_options

Gets a list of available report measurement options. [Note]

Request

Headers

Accept-Language
string

You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.

Content-Type
string

Represents the media type of the resource. Defaults to application/json.

Authorization
string

The key value to use for API requests. Instructions for getting API keys are in "how to generate API Keys".

Path Params

app_name
Requiredstring

Airbridge App Name. (Unique ID)

Request
curl -X GET 'https://api.airbridge.io/dataspec/v1/apps/{app_name}/retention-report/measurement_options' \ -H 'Accept-Language: ko' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'

Response

200SUCCESS

404ERROR

There is an error in the field provided, or there is no such resource.

Response
{ "data": [ { "key": "general_retention", "name": "General", "description": "The user retention is measured based on all Start Events that occurred during the set date range. For example, the Return Event that occurred on 3/3 is attributed to both Channel A and B. <br /><i>launch</i>\n<img src=\"https://static.airbridge.io/images/retention_measurement_tooltip_img/img_general.png\">\n<br /><i>launch</i>\n<a href=\"https://help.airbridge.io/en/guides/retention-report-viewing#general-mode\">Learn More</a>" }, { "key": "confined_retention", "name": "Confined", "description": "The user retention is measured based on the latest Start Event that occurred during the set date range. For example, the Return Event that occurred on 3/3 is attributed to Channel B only. <br /><i>launch</i><img src=\"https://static.airbridge.io/images/retention_measurement_tooltip_img/img_confined.png\">\n<br /><i>launch</i>\n<a href=\"https://help.airbridge.io/en/guides/retention-report-viewing#confined-mode\">Learn More</a>" }, { "key": "specific_retention", "name": "Specific", "description": "The user retention is measured based on the latest Start Event that occurred during the set date range. The Return Event is attributed when it occurs within the attribution window initiated by the Start Event. This option will be available soon. " } ]}
Response
{ "type": "about:blank", "title": "Not Found", "status": 404, "traceId": "1-000000-000000000000000"}