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.

    groupBy.fields
    Requiredstring[]

    Report "Group By".

    'Group By' is necessary when seeking a more detailed view in reports. This specification will allow reports to be grouped according to desired criteria. The 'Report GroupBys' for a comprehensive list of available options.

    The maximum threshold is 4.

    groupBy.cohorts
    object[]

    The filter for providing 'group by' items.

    groupBy.cohorts[0].id
    Requirednumber

    The groupBys to filter by.

    Only values defined within groupBys can be used.

    groupBy.cohorts[0].name
    Requiredstring

    The operator to apply to the filter.

    groupBy.cohorts[0].definition
    Requiredobject

    The value to apply to the filter.

    filters
    Requiredobject[]

    The filter for providing 'group by' items.

    filters[0].field
    Requiredstring

    The groupBys to filter by.

    Only values defined within groupBys can be used.

    filters[0].filterType
    Requiredenum

    The operator to apply to the filter.

    ENUM VALUES
    IN

    In. In Actuals reports, this corresponds to equals (is, =).

    NOT IN

    Not in. In Actuals reports, this corresponds to is not, ≠.

    LIKE

    Contains. ∋

    NOT LIKE

    Does not contain. ∌

    EXIST

    Value exists.

    NOT EXIST

    Value does not exist.

    filters[0].values
    string[]

    The value to apply to the filter.

    sorts
    Requiredobject[]

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

    sorts[0].fieldName
    Requiredstring

    Values within 'groupBys' or 'metrics' serve as criteria for sorting.

    sorts[0].isAscending
    boolean

    Sort by ascending (A-Z) or not. (Default: true)

    keyword
    string
    pagination
    object
    pagination.skip
    Requiredinteger
    pagination.size
    Requiredinteger
    Request
    12345
    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
    12345678910111213141516171819202122232425262728293031323334353637
    {
  "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
    12345
    {
  "data": {
    "taskId": "5e286bd4-b4b1-4c04-8f6a-123456789abc"
  }
}
    Response
    123456
    {
  "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
    1234
    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
    1234567
    {
  "task": {
    "status": "RUNNING",
    "taskId": "5e286bd4-b4b1-4c04-8f6a-670dc7ce637d",
    "endedAt": "2022-01-17T19:10:00.286939+09:00"
  }
}
    Response
    12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758
    {
  "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
    123456
    {
  "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
    1234
    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
    1234567891011121314151617181920212223242526272829303132333435363738
    {
  "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
    123456
    {
  "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
    1234
    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
    12345678910111213141516171819202122232425262728293031323334353637383940414243444546
    {
  "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
    123456
    {
  "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
    1234
    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
    1234567891011121314
    {
  "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
    123456
    {
  "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
    1234
    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
    12345678910111213141516171819
    {
  "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
    123456
    {
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "traceId": "1-000000-000000000000000"
}