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

# 리포트 생성하기

액츄얼스 리포트(Actuals Report)는 트래킹하고 있는 데이터를 자유롭게 확인할 수 있는 통계 리포트입니다.

에어브릿지에서 제공하는 다양한 데이터 필드를 활용하여 메트릭을 지정하고 특정 기준(그룹바이)들로 데이터를 세분화하거나 필터를 적용하는 등 원하는 형태로 리포트를 커스텀하게 구성할 수 있습니다.

<Accordion title="웹 식별자">
  웹 환경에서 고유 유저를 집계하는 기준은 '[쿠키 ID](/ko/guides/identifiers#%EC%BF%A0%ED%82%A4-id)'와 '[유저 ID](/ko/guides/identifiers#%EC%9C%A0%EC%A0%80-id)'입니다.

  * 쿠키 ID: 로그인 여부와 관계없이 서비스에 유입된 전체 유저가 집계됩니다.
  * 유저 ID: 로그인 정보를 활용해 서비스에서 1명의 회원으로 구분되는 유저가 집계됩니다. 웹 SDK에 유저를 식별하는 속성(user.externalUserID)이 설정돼야 User ID를 수집할 수 있습니다. 자세한 내용은 [개발자 가이드](/ko/developers/web-sdk#init%EC%8B%9C-%EC%82%AC%EC%9A%A9%EC%9E%90-%EC%8B%9D%EB%B3%84%EC%9E%90-%EB%B0%8F-%EC%86%8D%EC%84%B1-%EC%84%A4%EC%A0%95)를 참고해 주세요.
</Accordion>

Actuals Report의 통계 데이터를 요청합니다.

rate limit: 일반적인 사용량에는 별도의 제한이 없습니다. 다만, 서비스 안정성을 위협하는 과도한 요청이 감지될 경우, 일시적으로 429 Too Many Requests 응답이 반환될 수 있습니다.

<Card title="Try API Request" icon="rectangle-api" horizontal href="https://www.postman.com/airbridge-engineering/workspace/airbridge-api/request/22395869-66ddc9d2-2c1b-4911-89a6-7b539706c76e" />

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

<h2 id="리포트-생성하기-request">
  Request
</h2>

***

<h3 id="리포트-생성하기-headers">
  Headers
</h3>

<ParamField header="Accept-Language" type="string">
  API 요청 및 결과 반환에 사용할 언어를 지정할 수 있습니다. ISO-639-1 포맷을 따릅니다.
</ParamField>

<ParamField header="Content-Type" type="string">
  리소스의 미디어 타입을 나타냅니다. 기본값으로 `application/json`을 사용합니다.
</ParamField>

<ParamField header="Authorization" type="string">
  API 요청에 사용하는 키값입니다. [키값 생성 및 조회 방법](/ko/references/introduction)을 확인하여 획득할 수 있습니다.
</ParamField>

<h3 id="리포트-생성하기-path-params">
  Path Params
</h3>

<ParamField path="app_name" type="string" required>
  에어브릿지 앱 이름(App Name)
</ParamField>

<h3 id="리포트-생성하기-body-params">
  Body Params
</h3>

<ParamField body="from" type="string" required>
  요청할 리포트 데이터의 시작일.

  * `YYYY-MM-DD` 형태입니다.
  * 에어브릿지 앱의 타임존이 적용된 날짜이어야 합니다.
</ParamField>

<ParamField body="to" type="string">
  요청할 리포트 데이터의 종료일.

  * `YYYY-MM-DD` 형태입니다.
  * 에어브릿지 앱의 타임존이 적용된 날짜이어야 합니다.
  * 현재 날짜까지 설정할 수 있으며 한 번에 조회할 수 있는 최대 기간은 400일입니다.
</ParamField>

<ParamField body="groupBys" type="string[]" required>
  리포트 그룹바이.

  세분화하여 보고자 하는 항목을 ‘그룹바이'으로 설정하여 리포트를 조회할 수 있습니다. 액츄얼스 리포트에서 선택할 수 있는 전체 그룹바이 리스트는 [메타데이터 가져오기 (GroupBy) API](/ko/references/actuals-report/get-metadata-groupby)를 통해서 확인 할 수 있습니다.

  최대 10개까지 설정할 수 있습니다.
</ParamField>

<ParamField body="metrics" type="string[]" required>
  리포트 메트릭.

  메트릭으로 다양한 광고 성과 데이터를 조회할 수 있습니다. 액츄얼스 리포트에서 선택할 수 있는 전체 메트릭 리스트는 [메타데이터 가져오기 (Metric) API](/ko/references/actuals-report/get-metadata-metric)를 통해서 확인 할 수 있습니다.

  최대 20개까지 설정할 수 있습니다.
</ParamField>

<ParamField body="filters" type="object[]" required>
  '그룹바이'로 제공하는 항목들에 대한 필터.

  조건을 만족하는 데이터에 대한 통계 데이터를 리포트에서 조회할 수 있습니다.

  <Expandable title="하위 변수">
    <ParamField body="filters[0].dimension" type="string" required>
      필터를 지정할 그룹바이.

      `groupBys` 내에 정의된 값만 사용하실 수 있습니다.
    </ParamField>

    <ParamField body="filters[0].filterType" type="enum" required>
      필터에 적용할 연산자.

      | 벨류          | 설명                                            |
      | ----------- | --------------------------------------------- |
      | `IN`        | 속해있다. 액츄얼스 리포트에서는 같다(is, =)에 대응합니다.           |
      | `NOT IN`    | 속해있지 않다. 액츄얼스 리포트에서는 같지 않다(is not, ≠)에 대응합니다. |
      | `LIKE`      | 포함한다. (contains, ∋)                           |
      | `NOT LIKE`  | 포함하지 않는다. (does not contain, ∌)               |
      | `EXIST`     | 값이 존재한다. (exists)                             |
      | `NOT EXIST` | 값이 존재하지 않는다. (does not exist)                 |
    </ParamField>

    <ParamField body="filters[0].values" type="string[]">
      필터에 적용할 값.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sorts" type="object[]" required>
  '그룹바이' 또는 '메트릭'을 기준으로 리포트 데이터를 정렬할 수 있습니다.

  <Expandable title="하위 변수">
    <ParamField body="sorts[0].fieldName" type="string" required>
      정렬에 사용할 그룹바이 또는 메트릭.

      `groupBys` 또는 `metrics` 내에 정의된 값만 사용하실 수 있습니다.
    </ParamField>

    <ParamField body="sorts[0].isAscending" type="boolean">
      정렬 기준의 오름차순(A-Z) 여부. (기본값: `true`)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="option" type="object">
  추가 옵션을 설정할 수 있습니다.

  <Expandable title="하위 변수">
    <ParamField body="option.eventTimestampSource" type="enum">
      이벤트가 발생한 시각을 확인할 수 있습니다. event\_occurred\_date가 기본 설정입니다.

      | 벨류                    | 설명                         |
      | --------------------- | -------------------------- |
      | `target_event_date`   | 해당 이벤트의 타겟 이벤트가 발생한 시각입니다. |
      | `event_occurred_date` | 해당 이벤트가 발생한 시각입니다.         |
      | `touchpoint_date`     | 해당 이벤트의 터치포인트가 발생한 시각입니다.  |
    </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/v7/apps/{app_name}/actuals/query' \
    -H 'Accept-Language: ko' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}' \
    -d '{
    "from": "2022-11-04",
    "groupBys": [
      "event_source",
      "event_type",
      "event_category"
    ],
    "metrics": [
      "app_events"
    ],
    "filters": [
      {
        "dimension": "channel",
        "filterType": "IN",
        "values": [
          "App"
        ]
      }
    ],
    "sorts": [
      {
        "fieldName": "event_type",
        "isAscending": true
      }
    ]
  }'
  ```
</RequestExample>

<h2 id="리포트-생성하기-response">
  Response
</h2>

***

### 200

**`task.status`**

<div style={{ overflowX: 'auto' }}>
  <table style={{ display: 'table' }}>
    <tbody>
      <tr>
        <td style={{"minWidth":"130px"}}>
          `PENDING`
        </td>

        <td>
          데이터 집계를 위한 준비를 하고 있습니다.
        </td>
      </tr>

      <tr>
        <td>
          `RUNNING`
        </td>

        <td>
          데이터를 집계중입니다.
        </td>
      </tr>

      <tr>
        <td>
          `SUCCESS`
        </td>

        <td>
          집계가 완료되어 결과값을 반환합니다.
        </td>
      </tr>

      <tr>
        <td>
          `FAILURE`
        </td>

        <td>
          요청이 실패하였습니다.
        </td>
      </tr>

      <tr>
        <td>
          `CANCELED`
        </td>

        <td>
          요청이 취소되었습니다.
        </td>
      </tr>
    </tbody>
  </table>
</div>

### 404

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "task": {
      "status": "RUNNING",
      "taskId": "5e286bd4-b4b1-4c04-8f6a-670dc7ce637d"
    }
  }
  ```

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