> For the complete documentation index, see [llms.txt](https://toss-ads.gitbook.io/toss-ads/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://toss-ads.gitbook.io/toss-ads/references/reporting.md).

# Reporting

Reporting API는 광고 성과 데이터를 조회하는 API예요. Reporting API로 조회한 성과 수치는 같은 조건으로 조회한 광고주센터 맞춤 보고서의 수치와 항상 같아요. 두 곳 모두 같은 데이터와 스펙을 쓰기 때문이에요.

조회할 수 있는 성과·기준 필드 목록은 [Reporting (Data Spec)](/toss-ads/references/reporting-data-spec.md)에서 볼 수 있어요.

## 데이터 기준

* 데이터는 **KST 기준**이며 **2025-08-01**부터 제공해요.
* 지금은 보존 기간 제한이 없지만, 추후 정책에 따라 제한될 수 있어요.
* 성과 데이터는 **30분 단위**로 업데이트돼요.
* 도달 수 같은 고유(unique) 지표는 근사 집계 방식을 써서 약 1%의 오차가 있을 수 있어요.

***

## 1. 리포트 조회 (Report Query)

리포트 조회 API는 날짜·캠페인처럼 결과를 나눠 볼 기준(dimensions)과 노출 수·클릭 수 같은 성과(metrics)를 정해, 원하는 기간의 광고 성과 데이터를 조회하는 API예요. 조회 대상은 요청에 사용한 토큰에 연결된 광고계정으로 한정돼요.

요청하면 그 응답으로 결과 전체(최대 100,000행)를 페이징 없이 한 번에 받아요(동기 방식). 조회는 최대 30초까지 기다리고, 그 안에 끝나지 않으면 에러로 응답해요.

### 요청

아래 주소로 POST 요청을 보내요. Authorization 헤더에 `ads:report.read` 권한이 포함된 Access Token을 `Bearer {access_token}` 형식으로 넣어 주세요.

<mark style="color:green;">**`POST`**</mark> <mark style="color:green;"></mark><mark style="color:green;"><https://tossads-api.toss.im/v1/reports/query></mark>

```json
curl -X POST "https://tossads-api.toss.im/v1/reports/query" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "period": { "from": "2026-08-01", "to": "2026-08-31" },
    "metrics": ["impressions", "clicks", "ctr", "spend"],
    "dimensions": ["event_date", "campaign_id", "campaign_name"],
    "filters": [
      { "operator": "in", "field": "campaign_id", "values": ["12345", "12346"] }
    ],
    "sorts": [
      { "field": "event_date", "direction": "desc" }
    ],
    "limit": 100000,
    "conversionAttributionWindowDays": 30
  }'
```

<table><thead><tr><th width="124.33334350585938">필드</th><th width="123.77777099609375">타입</th><th width="104.11111450195312">필수</th><th>설명</th></tr></thead><tbody><tr><td><code>period</code></td><td>object</td><td>O</td><td><p>조회 기간이에요. </p><p><code>from</code>/<code>to</code>를 yyyy-MM-dd(KST) 형식으로 지정하고, 최대 190일까지 조회할 수 있어요.</p></td></tr><tr><td><code>metrics</code></td><td>string[]</td><td>O</td><td><p>조회할 성과 항목이에요. </p><p>예: impressions(노출 수), clicks(클릭 수).</p><p>최소 1개, 최대 20개까지 넣을 수 있어요. </p><p>넣을 수 있는 값은 <a href="#id-2.-metric-report-metrics">metric 스펙 조회 API</a>로 확인할 수 있어요.</p></td></tr><tr><td><code>dimensions</code></td><td>string[]</td><td>X</td><td><p>결과를 나눠 볼 기준이에요. </p><p>예: event_date를 넣으면 날짜별로, campaign_id를 넣으면 캠페인별로 결과가 나뉘어요. </p><p>최대 10개까지 넣을 수 있고, 넣지 않으면 기간 전체 합계 1행을 받아요. </p><p>넣을 수 있는 값은 <a href="#id-3.-dimension-report-dimensions">dimension 스펙 조회 API</a>로 확인할 수 있어요.</p></td></tr><tr><td><code>filters</code></td><td>object[]</td><td>X</td><td><p>operator, field, value(s)를 조합해 원하는 데이터만 골라 받는 조건이에요. <code>{ }</code> 하나가 조건 하나예요.<br><br>field에는 무엇을 기준으로 고를지 넣어요. 캠페인으로 고르려면 campaign_id를 넣어요. <a href="#id-3.-dimension-report-dimensions">dimension 스펙 조회</a>에서 filterable이 true인 기준만 넣을 수 있어요.<br></p><ul><li>캠페인 하나만 볼 때(예: 캠페인 A): <code>operator</code>에 <code>equal</code>, <code>value</code>에 캠페인 A의 ID를 넣어요.</li><li>캠페인 여러 개를 볼 때(예: 캠페인 A, B, C): <code>operator</code>에 <code>in</code>, <code>values</code>에 캠페인 A, B, C의 ID 목록을 넣어요.</li></ul><p></p><p>조건을 여러 개 넣으면 모든 조건을 만족하는 데이터만 와요.<br>예: <code>{ "operator": "in", "field": "campaign_id", "values": ["캠페인A_ID", "캠페인B_ID", "캠페인C_ID"] }</code></p></td></tr><tr><td><code>sorts</code></td><td>object[]</td><td>X</td><td><p>결과를 정렬하는 조건이에요. </p><p>field에는 정렬 기준을, direction에는 정렬 방향(asc 오름차순, desc 내림차순)을 넣어 주세요. field에는 이번 요청의 metrics나 dimensions에 넣은 값만 쓸 수 있어요. </p><p>넣지 않으면 첫 번째 metric 기준 내림차순으로 정렬해요.</p></td></tr><tr><td><code>conversionAttributionWindowDays</code></td><td>number</td><td>X</td><td><p>광고를 보거나 클릭한 날부터 며칠 안에 일어난 전환(구매, 가입 등)까지 광고 성과로 볼지 정하는 기간(일)이에요. </p><p>0~90 사이로 넣을 수 있고, 넣지 않으면 30일이 적용돼요. </p><p>이 기간은 전환에만 적용돼요. 노출 수·클릭 수는 기간과 상관없이 조회 기간 안에 일어난 만큼 집계돼요.<br>예: 7을 넣으면 광고를 보거나 클릭한 날부터 7일 안에 일어난 전환만 집계돼요.</p></td></tr><tr><td><code>limit</code></td><td>number</td><td>X</td><td><p>받을 결과의 최대 개수예요. </p><p>100,000까지 넣을 수 있고, 넣지 않으면 100,000이 적용돼요. 결과가 limit에 넣은 값보다 많으면 그 개수까지만 오고, 나머지는 오지 않아요.</p></td></tr></tbody></table>

### 응답

조회에 성공하면 아래와 같은 응답을 받아요.

```json
{
  "resultType": "SUCCESS",
  "success": {
    "rows": [
      {
        "event_date": "2026-08-31",
        "campaign_id": "12345",
        "campaign_name": "가을 프로모션",
        "impressions": 150000,
        "clicks": 4200,
        "ctr": 2.800000000000,
        "spend": 1250000
      },
      {
        "event_date": "2026-08-31",
        "campaign_id": "12346",
        "campaign_name": "",
        "impressions": 98000,
        "clicks": 1900,
        "ctr": 1.938775510204,
        "spend": 640000
      }
    ],
    "rowCount": 2
  }
}
```

<table><thead><tr><th width="189">필드</th><th width="166.33331298828125">타입</th><th>설명</th></tr></thead><tbody><tr><td><code>rows</code></td><td>object[]</td><td><p>조회한 데이터예요. </p><p>요청한 dimensions별로 나뉘어 오고, <code>{ }</code> 하나에 그 결과의 dimensions 값과 metrics 값이 담겨요.</p></td></tr><tr><td><code>rowCount</code></td><td>number</td><td><p>rows에 담긴 결과 개수예요. </p><p>결과가 limit보다 많으면 limit 개수까지만 와요. 그래서 rowCount가 limit과 같다면 받지 못한 결과가 있을 수 있어요. 이때는 조회 기간을 나누거나 filters로 범위를 좁혀 다시 조회해 주세요.</p></td></tr></tbody></table>

**rows 안의 값은 아래 규칙을 따라요.**

* dimension 값은 항상 문자열(string)이에요. 원본이 숫자여도 `"12345"`처럼 문자열로 반환돼요.
* 값이 없는 dimension은 `null`이 아니라 빈 문자열(`""`)로 와요.
* metric 값은 숫자(number)예요. `ctr`처럼 소수인 값은 소수 자릿수가 그대로 와요.
* 값이 숫자·통화·퍼센트·날짜 중 무엇인지는 [dimension 스펙 조회](#id-3.-dimension-report-dimensions)의 `fieldFormat`, [metric 스펙 조회](#id-2.-metric-report-metrics)의 `fieldUnit`으로 확인해 주세요.

### 에러

| 상황               | 응답                                                                                                                                            |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 요청 검증 실패         | <p>HTTP 200 + <code>FAIL</code> </p><p>검증 에러 메시지를 반환해요. (예: 기간 190일 초과, 존재하지 않는 metric/dimension 키, <code>filterable=false</code> 필드로 필터)</p> |
| 조회 타임아웃 (30초 초과) | <p>HTTP 200 + <code>FAIL</code> </p><p>리포트 조회 시간이 초과되었어요. 조회 기간을 짧게 나누거나, 필터로 범위를 좁히거나, dimensions 수를 줄여 다시 시도해 주세요.</p>                      |
| 일시적 조회 실패        | <p>HTTP 200 + <code>FAIL</code> </p><p>리포트 조회에 실패했어요. 잠시 후 다시 시도해 주세요.</p>                                                                    |

***

## 2. metric 스펙 조회 (Report Metrics)

metric 스펙 조회 API는 리포트 조회의 metrics에 넣을 수 있는 성과(노출 수, 클릭 수 등) 목록을 알려주는 API예요. 리포트 조회의 metrics에는 이 목록에 있는 key만 넣을 수 있어요. 성과 항목은 새로 추가되거나 바뀔 수 있으니, 목록을 하드코딩하지 말고 이 API로 받은 최신 목록을 쓰는 걸 권장해요.

### 요청

아래 주소로 GET 요청을 보내요. Authorization 헤더에 `ads:report.read` 권한이 포함된 Access Token을 `Bearer {access_token}` 형식으로 넣어 주세요. Authorization 헤더 외에 따로 보내는 값은 없어요.

<mark style="color:green;">**`GET`**</mark> <mark style="color:green;"></mark><mark style="color:green;"><https://tossads-api.toss.im/v1/reports/metrics></mark>

```json
curl -X GET "https://tossads-api.toss.im/v1/reports/metrics" \
  -H "Authorization: Bearer {access_token}"
```

### 응답

조회에 성공하면 아래와 같은 응답을 받아요.

```json
{
  "resultType": "SUCCESS",
  "success": {
    "metrics": [
      {
        "key": "impressions",
        "displayName": "노출수",
        "description": "...",
        "fieldUnit": "number",
        "supportedAdTypes": [
          "배너광고",
          "..."
        ]
      }
    ]
  }
}
```

<table><thead><tr><th width="247.375">필드</th><th width="138.875">타입</th><th>설명</th></tr></thead><tbody><tr><td><code>metrics[].key</code></td><td>string</td><td><p>리포트  조회에 사용하는 metric 이름(Reporting Key)이에요.</p><p> <code>/query</code>의 <code>metrics</code>·<code>sorts.field</code>에 사용해요.</p></td></tr><tr><td><code>metrics[].displayName</code></td><td>string</td><td>metric 표시 이름이에요.</td></tr><tr><td><code>metrics[].description</code></td><td>string</td><td>metric 설명이에요.</td></tr><tr><td><code>metrics[].fieldUnit</code></td><td>string</td><td><p>metric 값의 단위예요. </p><p><code>number</code> | <code>currency</code> | <code>percentage</code> 중 하나예요.</p></td></tr><tr><td><code>metrics[].supportedAdTypes</code></td><td>string[]</td><td>이 metric을 사용할 수 있는 광고 상품 유형 목록이에요.</td></tr></tbody></table>

***

## 3. dimension 스펙 조회 (Report Dimensions)

dimension 스펙 조회 API는 리포트를 날짜별, 캠페인별처럼 무엇별로 볼지 정하는 기준의 목록을 알려줘요. 리포트 조회의 dimensions에는 이 목록에 있는 key만 넣을 수 있어요. 이 key는 데이터를 고르는 filters와 정렬하는 sorts에도 쓸 수 있어요. 단, filters에는 응답의 filterable이 true인 기준만 넣을 수 있어요.

### 요청

아래 주소로 GET 요청을 보내요. Authorization 헤더에 `ads:report.read` 권한이 포함된 Access Token을 `Bearer {access_token}` 형식으로 넣어 주세요. Authorization 헤더 외에 따로 보내는 값은 없어요.

<mark style="color:green;">**`GET`**</mark> <mark style="color:green;"></mark><mark style="color:green;"><https://tossads-api.toss.im/v1/reports/dimensions></mark>

```json
curl -X GET "https://tossads-api.toss.im/v1/reports/dimensions" \
  -H "Authorization: Bearer {access_token}"
```

### 응답

조회에 성공하면 아래와 같은 응답을 받아요.

```json
{
  "resultType": "SUCCESS",
  "success": {
    "dimensions": [
      {
        "key": "campaign_id",
        "displayName": "캠페인 ID",
        "description": "...",
        "fieldFormat": "number",
        "filterable": true,
        "supportedAdTypes": [
          "배너광고",
          "..."
        ]
      }
    ]
  }
}
```

<table><thead><tr><th width="231.83331298828125">필드</th><th width="127.33331298828125">타입</th><th>설명</th></tr></thead><tbody><tr><td><code>dimensions[].key</code></td><td>string</td><td><p>리포트 조회 요청에 사용하는 dimension 이름(Reporting Key)이에요. </p><p><code>/query</code>의 <code>dimensions</code>·<code>filters.field</code>·<code>sorts.field</code>에 사용해요.</p></td></tr><tr><td><code>dimensions[].displayName</code></td><td>string</td><td>dimension 표시 이름이에요.</td></tr><tr><td><code>dimensions[].description</code></td><td>string</td><td>dimension 설명이에요.</td></tr><tr><td><code>dimensions[].fieldFormat</code></td><td>string</td><td><p>dimension 값의 실제 형식이에요.</p><p>리포트 조회 결과에서 dimension 값은 모두 문자열(string)로 오지만, 이 필드로 숫자인지 날짜인지 등을 확인할 수 있어요.</p><p></p><p><code>number</code> | <code>string</code> | <code>currency</code> | <code>percentage</code> | <code>date</code> | <code>date-time</code> 중 하나예요. </p></td></tr><tr><td><code>dimensions[].filterable</code></td><td>boolean</td><td><p>이 dimension으로 필터를 걸 수 있는지 여부예요. </p><p><code>true</code>인 dimension만 리포트 조회 요청의 <code>filters</code>에서 <code>field</code>로 지정할 수 있어요.</p></td></tr><tr><td><code>dimensions[].supportedAdTypes</code></td><td>string[]</td><td>이 dimension을 사용할 수 있는 광고 상품 유형 목록이에요.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://toss-ads.gitbook.io/toss-ads/references/reporting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.