• APIリファレンス

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
必須string

Airbridge App Name. (Unique ID)

Body Params

from
必須string
to
必須string
granularity
必須enum
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
必須enum[]
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
必須enum[]
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
必須enum
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
必須object
filters
必須object[]
sorts
必須object[]
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
必須string

Airbridge App Name. (Unique ID)

task_id
必須string

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
必須string

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
必須string

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
必須string

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
必須string

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"}