> ## Documentation Index
> Fetch the complete documentation index at: https://help.airbridge.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Request 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 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.

<Card title="Try API Request" icon="rectangle-api" horizontal href="https://www.postman.com/airbridge-engineering/workspace/airbridge-api/request/22395869-24a5ae6f-b649-4fa5-8b35-dcac185e28d7" />

```text POST theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
https://api.airbridge.io/reports/api/v5/apps/{app_name}/retention/query
```

<h2 id="request-report-request">
  Request
</h2>

***

<h3 id="request-report-headers">
  Headers
</h3>

<ParamField header="Accept-Language" type="string">
  You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.
</ParamField>

<ParamField header="Content-Type" type="string">
  Represents the media type of the resource. Defaults to `application/json`.
</ParamField>

<ParamField header="Authorization" type="string">
  The key value to use for API requests. Instructions for getting API keys are in "[how to generate API Keys](/en/references/introduction#authorization)".
</ParamField>

<h3 id="request-report-path-params">
  Path Params
</h3>

<ParamField path="app_name" type="string" required>
  Airbridge App Name. (Unique ID)
</ParamField>

<h3 id="request-report-body-params">
  Body Params
</h3>

<ParamField body="from" type="string" required>
  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.
</ParamField>

<ParamField body="to" type="string" required>
  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.
</ParamField>

<ParamField body="granularity" type="enum" required>
  The analytics interval period.

  | Value    | Description                                                                                                                                                                                                                   |
  | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `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.                                                                                                       |
</ParamField>

<ParamField body="intervalsPeriod" type="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.
</ParamField>

<ParamField body="startEvents" type="enum[]" required>
  The event that initiates a User Journey in the time period set. Choose at least 1 event.

  | Value                    | Description                                                                                       |
  | ------------------------ | ------------------------------------------------------------------------------------------------- |
  | `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.        |
</ParamField>

<ParamField body="returnEvents" type="enum[]" required>
  An in-app event performed by the user after performing a Start Event.

  It is possible to set up multiple return events.

  | Value                      | Description                                                                                       |
  | -------------------------- | ------------------------------------------------------------------------------------------------- |
  | `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.                       |
</ParamField>

<ParamField body="measurementOption" type="enum" required>
  The option to view the retention by unique users or by user journeys that are separated by Start Events. \[[Reference](https://help.airbridge.io/hc/en-us/articles/4405204740249-Retention#measurement-option)]

  | Value                | Description                                                                                                                                                 |
  | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `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. |
</ParamField>

<ParamField body="groupBy" type="object" required>
  Allows you to set a group by to divide the numbers for the metric you want to see.

  <Expandable title="child attributes">
    <ParamField body="groupBy.fields" type="string[]" required>
      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](https://docs.google.com/spreadsheets/d/13ThNnryqRmZQwJVecM8lZ2OB7LzA8s3cwLlQBGpbXLg/edit#gid=1419762398)' for a comprehensive list of available options.

      The maximum threshold is 4.
    </ParamField>

    <ParamField body="groupBy.cohorts" type="object[]">
      The filter for providing 'group by' items.

      <Expandable title="child attributes">
        <ParamField body="groupBy.cohorts[0].id" type="number" required>
          The groupBys to filter by.

          Only values defined within `groupBys` can be used.
        </ParamField>

        <ParamField body="groupBy.cohorts[0].name" type="string" required>
          The operator to apply to the filter.
        </ParamField>

        <ParamField body="groupBy.cohorts[0].definition" type="object" required>
          The value to apply to the filter.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="filters" type="object[]" required>
  The filter for providing 'group by' items.

  <Expandable title="child attributes">
    <ParamField body="filters[0].field" type="string" required>
      The groupBys to filter by.

      Only values defined within `groupBys` can be used.
    </ParamField>

    <ParamField body="filters[0].filterType" type="enum" required>
      The operator to apply to the filter.

      | Value       | Description                                                 |
      | ----------- | ----------------------------------------------------------- |
      | `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.                                       |
    </ParamField>

    <ParamField body="filters[0].values" type="string[]">
      The value to apply to the filter.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sorts" type="object[]" required>
  Sort report data by 'Group By' or 'Metric'.

  <Expandable title="child attributes">
    <ParamField body="sorts[0].fieldName" type="string" required>
      Values within 'groupBys' or 'metrics' serve as criteria for sorting.
    </ParamField>

    <ParamField body="sorts[0].isAscending" type="boolean">
      Sort by ascending (A-Z) or not. (Default: true)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="keyword" type="string" />

<ParamField body="pagination" type="object">
  <Expandable title="child attributes">
    <ParamField body="pagination.skip" type="integer" required />

    <ParamField body="pagination.size" type="integer" required />
  </Expandable>
</ParamField>

<RequestExample>
  ```shellscript Request theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  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
    }
  }'
  ```
</RequestExample>

<h2 id="request-report-response">
  Response
</h2>

***

### 200

### 400

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "data": {
      "taskId": "5e286bd4-b4b1-4c04-8f6a-123456789abc"
    }
  }
  ```

  ```json 400 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "traceId": "1-000000-000000000000000"
  }
  ```
</ResponseExample>