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

# Report API

> Query your app's ad performance data programmatically using the DARO Report API. Group data by app, ad unit, ad format, country, and platform.

## Overview

The DARO Report API allows you to programmatically query ad performance data outside of the DARO dashboard. Retrieve key metrics such as revenue, impressions, and clicks grouped by various dimensions.

## Authentication

You must obtain an Access Token before using the Report API.

### 1. Get Your Secret Key

Find your `report_secret_key` in the [DARO Dashboard](https://dashboard.daro.so/service/account).

<Note>
  If your `report_secret_key` has not been issued yet, please contact your account manager.
</Note>

### 2. Issue an Access Token

```
POST https://api.daro.so/report/v1/auth
```

**Request Body:**

```json theme={null}
{
  "secretKey": "YOUR_REPORT_SECRET_KEY"
}
```

**Response:**

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": "2025-01-01T01:00:00Z"
}
```

| Field       | Type   | Description                           |
| ----------- | ------ | ------------------------------------- |
| accessToken | String | Authentication token for API requests |
| expiresAt   | String | Token expiration time                 |

### 3. Use the Token in API Requests

Include the issued `accessToken` in the HTTP header when calling the API.

```
Authorization: Bearer {accessToken}
```

**Request Example:**

```bash theme={null}
curl -X POST "https://api.daro.so/report/v1/auth" \
  -H "Content-Type: application/json" \
  -d '{"secretKey": "YOUR_REPORT_SECRET_KEY"}'
```

<Warning>
  The `accessToken` expires at the time specified in `expiresAt`. Once expired, you must issue a new token via the `/report/v1/auth` endpoint.
</Warning>

## API Policy

### Authentication & Authorization

Your Secret Key must be kept secure and should never be shared with others.

### Rate Limit

The default request limit is 100 requests per minute. If you need a higher request volume, please contact the DARO business team.

## Report Query

```
GET https://api.daro.so/report/v1/metrics
```

## Request Parameters

All parameters are passed as query strings.

| Parameter              | Type   | Description                                                                               | Example                                |     |
| ---------------------- | ------ | ----------------------------------------------------------------------------------------- | -------------------------------------- | --- |
| from *(required)*      | String | Start date (`YYYY-MM-DD`)                                                                 | `2025-01-01`                           |     |
| to *(required)*        | String | End date (`YYYY-MM-DD`). Must be after `from`, and the date range must not exceed 90 days | `2025-01-31`                           |     |
| group\_by *(required)* | String | Grouping dimension (comma-separated for multiple)                                         | `app,ad_format`                        |     |
| app                    | String | Filter by specific app                                                                    | `your_app_key`                         |     |
| ad\_unit\_id           | String | Filter by specific ad unit                                                                | `fa1c6d2f-5016-467d-b54c-672299c7db4c` |     |
| ad\_format             | String | Filter by ad format                                                                       | `banner`                               |     |
| country                | String | Filter by country code                                                                    | `KR`                                   |     |
| platform               | String | Filter by platform                                                                        | `android`                              |     |
| page\_size             | Int    | Number of items per page (default: 10, max: 1000)                                         | `20`                                   |     |
| page\_number           | Int    |                                                                                           | Page number (default: 1)               | `1` |

### Available group\_by Values

| Value      | Description        |
| ---------- | ------------------ |
| app        | Group by app       |
| ad\_unit   | Group by ad unit   |
| ad\_format | Group by ad format |
| country    | Group by country   |
| platform   | Group by platform  |

## Request Example

```bash theme={null}
curl -X GET "https://api.daro.so/report/v1/metrics?from=2025-01-01&to=2025-01-31&group_by=app,ad_format&page_size=20&page_number=1" \
  -H "Authorization: Bearer {accessToken}"
```

## Response

### Response Fields

| Field          | Type   | Description                                                |
| -------------- | ------ | ---------------------------------------------------------- |
| date           | String | Date                                                       |
| appKey         | String | App key (returned when `group_by` includes `app`)          |
| appName        | String | App name (returned when `group_by` includes `app`)         |
| adUnitName     | String | Ad unit name (returned when `group_by` includes `ad_unit`) |
| adFormat       | String | Ad format (returned when `group_by` includes `ad_format`)  |
| country        | String | Country code (returned when `group_by` includes `country`) |
| platform       | String | Platform (returned when `group_by` includes `platform`)    |
| revenue        | Float  | Revenue (USD)                                              |
| adRequest      | Int    | Number of ad requests                                      |
| matchedRequest | Int    | Number of matched requests                                 |
| impression     | Int    | Number of impressions                                      |
| click          | Int    | Number of clicks                                           |
| matchRate      | Float  | Match rate (matchedRequest / adRequest)                    |
| showRate       | Float  | Show rate (impression / matchedRequest)                    |
| ctr            | Float  | Click-through rate (click / impression)                    |
| ecpm           | Float  | eCPM (revenue / impression \* 1000)                        |

### Response Example

```json theme={null}
{
  "data": [
    {
      "date": "2025-01-01",
      "appKey": "your_app_key",
      "appName": "My App",
      "adFormat": "banner",
      "revenue": 123.45,
      "adRequest": 10000,
      "matchedRequest": 8500,
      "impression": 8000,
      "click": 160,
      "matchRate": 0.85,
      "showRate": 0.9412,
      "ctr": 0.02,
      "ecpm": 15.43
    },
    {
      "date": "2025-01-02",
      "appKey": "your_app_key",
      "appName": "My App",
      "adFormat": "interstitial",
      "revenue": 130.20,
      "adRequest": 11000,
      "matchedRequest": 9200,
      "impression": 8700,
      "click": 174,
      "matchRate": 0.8364,
      "showRate": 0.9457,
      "ctr": 0.02,
      "ecpm": 14.97
    }
  ],
  "page_size": 20,
  "page_number": 1,
  "total_count": 31
}
```

<Warning>
  Fields for dimensions not included in `group_by` are omitted from the response. For example, if you request with `group_by=app`, fields like `adUnitName`, `adFormat`, and `country` will not be included in the response.
</Warning>