> ## 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 Revenue Report allows you to view the revenue generated by users who installed the app or opened a deep link during the analysis period. Various revenue metrics and filters are available to create a customized report.

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

Request a Revenue 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-1f99e448-f982-4854-9127-c874bdfdefcc" />

```text POST theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
https://api.airbridge.io/reports/api/v3/apps/{app_name}/revenue/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="cohorts" type="object[]">
  Only one cohort can be set up.

  You can see an example of cohort code [here](https://www.postman.com/airbridge-engineering/workspace/airbridge-api/request/22395869-fe6e8212-2259-4bae-9306-0566e7786a68?ctx=documentation).

  <Expandable title="child attributes">
    <ParamField body="cohorts[0].id" type="number" required>
      The value should be entered as 0. Other values are not supported.
    </ParamField>

    <ParamField body="cohorts[0].name" type="string" required>
      The value should be entered as "Cohort". Other values are not supported.
    </ParamField>

    <ParamField body="cohorts[0].definition" type="object" required>
      Define the cohorts used by the Revenue Report. Always define sub-variables in the order `andClauses`, `orClauses`, `segment`. Check the relationship between each variable below.

      <Expandable title="child attributes">
        <ParamField body="cohorts[0].definition.andClauses" type="object[]" required>
          The highest-level condition in the cohort definition. All conditions you set are connected with an AND. You must set `negated` and `orClauses` as sub-variables.

          * `negated` (boolean): Sets whether the condition you set in `orClauses` is negated.

            * `true`: Negates the condition you set in `orClauses`, so the condition you set in `orClauses` is false.
            * `false`: Does not negate the condition set in `orClauses`. Therefore, the condition set in `orClauses` is true.

          cohorts\[0].definition.andClauses\[\*].**orClauses** | <em>Required</em> ・ object\[]

          The conditions you set in the child of `andClauses`. Connect all the conditions you set with an OR. You must set negated and segment as sub-variables.

          * `negated (boolean)`: Sets whether the condition set in `orClauses` is negated.

            * `true`: Negates the condition you set in `orClauses`, so the condition you set in `orClauses` is false.
            * `false`: Does not negate the condition set in the `orClauses`. Therefore, the condition set in the `orClauses` is true.

          cohorts\[0].definition.andClauses\[\*].orClauses\[\*].**segment** | <em>Required ・</em> object

          The minimum conditions for a cohort definition. You can set `event`, `filters`, and `time` as sub-variables.

          * `event` (object): You can define an event triggered by the user and the number of times it occurs. You can set `type`, `operator`, and `value` as sub-variables.

            * `type` (string): type (string): Sets the event generated by the user. You can set it to any event by using `any-event`. Other events that can be set can be found in the Event Key column of \[[Airbridge Data Spec](https://docs.google.com/spreadsheets/d/13ThNnryqRmZQwJVecM8lZ2OB7LzA8s3cwLlQBGpbXLg/edit#gid=1066355972)]>\[Revenue Report - Audience Events]. Please be aware of the use of ' ' and `_`.
            * `operator` (enum): You can set the comparison operator used for the number of times an event occurs. You can only use one of five: `equals`, `more than or equals`, `more than`, `less than or equals`, and `less than`.
            * `value` (number): You can set the number of times the event occurs. Please enter a natural number.
          * `filters` (object\[]): You can only see certain events out of the ones you have defined. It's the same as the had property in the cohort definition. You can set `field` and `filterType` as sub-variables.

            * `field` (string): Properties that can be set as filters. Please refer to the Property Key column of \[[Airbridge Data Spec](https://docs.google.com/spreadsheets/d/13ThNnryqRmZQwJVecM8lZ2OB7LzA8s3cwLlQBGpbXLg/edit#gid=66435896)] > \[Revenue Report - Audience Properties] for the properties that can be set.
            * `filterType` (enum): Sets the operators that can be used on the property. Depending on the property you set, the available operators and the values you set with the filter (none, value, values) change.

          | filterType                  | Property Data Type          | Sub-variables |
          | --------------------------- | --------------------------- | ------------- |
          | is / is not                 | string, boolean             | values        |
          | contains / does not contain | string                      | value         |
          | exists / does not exist     | string, boolean, int, float | N/A           |
          | equals / does not equal     | int, float                  | value         |
          | does not equal              | int, float                  | value         |
          | greater than or equals      | int, float                  | value         |
          | greater than                | int, float                  | value         |
          | less than or equals         | int, float                  | value         |
          | less than                   | int, float                  | value         |
          | between                     | int, float                  | values        |
          | does not between            | int, float                  | value         |

          * `time` (object): You can set conditions for when the event occurred. The subvariable will change based on the set condition.

            * `operator` (enum): Set the condition from `during`, `between`, or `since`. Only one of the three can be set. If the condition is `between`, the lookup period can be set from 1 February 2023. The maximum period you could set is 90 days.

          | Operator | Sub-variables        | Description                                    |
          | -------- | -------------------- | ---------------------------------------------- |
          | during   | values, isNowEnabled | isNowEnabled sets whether to include today     |
          | between  | values               | Values must have both start and end dates set. |
          | since    | values               | Set start date only                            |
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</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>
  </Expandable>
</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. |
</ParamField>

<ParamField body="intervalsPeriodIndexes" type="number[]">
  This defines the interval ranges provided for each granularity. Revenue Report results are split into multiple intervals depending on the selected granularity.

  * `0 (Day 0)` is not added automatically. It is included only when explicitly requested by the user.
  * When the granularity is `day`, `week`, or `month`, the selectable ranges are:

    * `0–180`for day
    * `0–52`for week
    * `0–36`for month
  * When the granularity is `hour` or `minute`, this option is not used. The interval values are fixed at:

    * `23`for hour
    * `59`for minute
</ParamField>

<ParamField body="startEvents" type="enum[]" required>
  The event that initiates a [User Journey](https://help.airbridge.io/hc/en-us/articles/4409764368409-Revenue?utm_source=Browsing#user-journey) in the time period set.

  Users who do not trigger the set event are not analyzed in the report.

  | Value                   | Description                                                                                      |
  | ----------------------- | ------------------------------------------------------------------------------------------------ |
  | `app_install`           | Install (App). Install events that occurred within the selected time period.                     |
  | `app_deeplink_open`     | Deeplink Open (App). Deeplink Open events that occurred within the selected time period.         |
  | `app_deeplink_pageview` | Deeplink Pageview (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.                     |
</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="metric" type="enum" required>
  Report "Metrics".

  | Value             | Description                                                                                                                                                           |
  | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `app_revenue`     | Revenue(App). The revenue generated by the users who performed the Start Event and the Return Event. (In local currency) Support cumulative, on-day aggregation type. |
  | `app_user_count`  | User Count (App). The total number of unique users who performed revenue events. Support cumulative, on-day aggregation type.                                         |
  | `app_event_count` | Event Count (App). The total number of revenue events. Support cumulative, on-day aggregation type.                                                                   |
  | `app_roas`        | ROAS (App). The return on ad spend of the users who performed the Start Event and the Retrun Event. (In local currency) Support cumulative aggregation type.          |
  | `app_arpu`        | ARPU (App). The average revenue per user who performed the Start Event. (In local currency) Support cumulative aggregation type.                                      |
  | `app_arppu`       | ARPPU (App). The average revenue per paying user who performed the Start Event. (In local currency) Support cumulative aggregation type.                              |
</ParamField>

<ParamField body="aggregationType" type="enum" required>
  View types for the report. \[[Reference](https://help.airbridge.io/hc/en-us/articles/4409764368409-Revenue?utm_source=Browsing#view-types)]

  | Value        | Description                                                                                                           |
  | ------------ | --------------------------------------------------------------------------------------------------------------------- |
  | `cumulative` | Cumulative aggregation. Accumulate numbers from the first day of the analysis period (Day 0) to the last day (Day N). |
  | `on-day`     | On Day (N-Day). View the isolated data of each day.                                                                   |
</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 `groupBy.dimensions` or `subMetrics` 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="resultSpec" type="object">
  The format of the result.

  <Expandable title="child attributes">
    <ParamField body="resultSpec.csv" type="object">
      The csv format of the result.

      <Expandable title="child attributes">
        <ParamField body="resultSpec.csv.includesMetadata" type="boolean">
          Whether to include metadata. (selected StartEvent, groupBy, etc.)
        </ParamField>

        <ParamField body="resultSpec.csv.includesTotal" type="boolean">
          Whether to include total value.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```shellscript Request theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  curl -X POST 'https://api.airbridge.io/reports/api/v3/apps/{app_name}/revenue/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",
    "groupBy": {
      "fields": [
        "channel"
      ]
    },
    "granularity": "day",
    "intervalsPeriodIndexes": [
      1,
      3,
      7
    ],
    "startEvents": [
      "app_install"
    ],
    "returnEvents": [
      "app_order_complete"
    ],
    "metric": "app_revenue",
    "aggregationType": "cumulative",
    "filters": [
      {
        "field": "campaign",
        "filterType": "IN",
        "values": [
          "App"
        ]
      }
    ],
    "sorts": [
      {
        "fieldName": "totalRevenue",
        "isAscending": true
      }
    ],
    "resultSpec": {
      "csv": {
        "includesTotal": true
      }
    }
  }'
  ```
</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-asdf1234zxcv"
    }
  }
  ```

  ```json 400 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {}
  ```
</ResponseExample>