> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Data reference
> Metrics, breakdowns, refresh cadence, and limits for the Kakao Keyword Ads data source in Adriel.
## Introduction
Kakao Keyword Ads is the search-keyword advertising platform operated by Kakao, the company behind KakaoTalk, Korea's dominant messaging app. Advertisers bid on search keywords, and the connector imports the resulting account, campaign, ad group, ad, and keyword architecture along with daily performance metrics through the Kakao Business Keyword Ad API.
As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration. Kakao Keyword Ads reports spend in Korean won (KRW) only.
To connect this data source, see [How to connect Kakao Keyword Ads to Adriel](/data-sources/g-n/kakao-keyword-ads/how-to-connect).
## Data refresh strategy
### Architecture data
Architecture covers ad accounts, campaigns, ad groups (광고그룹, mapped to ad sets), ads, and keywords. It refreshes twice daily at **4:00 PM UTC** and **5:00 AM UTC**.
### Reports data
Reports include daily performance for campaigns, ad sets, ads, and the device-target segmentation at ad-account level.
**Real-time.** Report data is fetched from Kakao on demand when a dashboard loads, so the latest values are always visible. On top of that, scheduled background syncs keep historical data consistent across several time windows.
**Refresh schedule.** Reports refresh on three overlapping schedules across the campaign, ad set, ad, and device-target (ad-account) breakdowns:
* **5:00 PM UTC daily** — syncs the last **9 days**
* **11:40 PM and 6:40 AM UTC daily** — syncs the last **3 days**
* **3:00 PM UTC on the 1st and 15th of each month** — syncs the last **30 days**
## Architecture levels
Ad account → Campaign → Ad group (광고그룹, ad set) → Ad → Keyword
## Date range limits
| Breakdown | Max range |
| --------- | --------- |
| Daily | 93 days |
| Weekly | 1 year |
| Monthly | 2 years |
A separate cap applies to hourly segmentation — see [Limitations](#limitations).
## Attribution windows
Conversions are tracked through the Kakao Pixel & SDK, which reports each conversion event on both a **1-day** and a **7-day** attribution window. Imported events carry a window suffix (for example `purchase_1D` and `purchase_7D`), so the same event can appear as two metrics. The standard Conversion value and Revenue metrics use Kakao's 7-day purchase value (`metrics.convPurchaseP7d`).
## Metrics
**How to read the columns**
**Data type** is one of: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
**API Key** in `code` style is the literal Kakao API field name. *Italic text* describes how a value is produced when it does not map to a single API field (Adriel-computed rates, cross-connector fallbacks, or aggregated values).
### Delivery
| Metric | Description | Data type | API Key |
| ----------- | -------------------------------------------------------------- | --------- | ----------------- |
| Impressions | Total times the ads were displayed, regardless of interaction. | Number | `metrics.imp` |
| CPM | Cost per thousand impressions (spend ÷ impressions × 1,000). | Currency | *Adriel-computed* |
### Click performance
| Metric | Description | Data type | API Key |
| ------------ | ----------------------------------------------------------------------- | ---------- | ----------------- |
| Clicks (all) | Total clicks recorded on the ad. | Number | `metrics.click` |
| Link clicks | Clicks on the ad's link. Same value as Clicks (all) for this connector. | Number | `metrics.click` |
| CTR | Click-through rate (clicks ÷ impressions). | Percentage | *Adriel-computed* |
| CPC | Cost per click (spend ÷ clicks). | Currency | *Adriel-computed* |
### Cost & spend
| Metric | Description | Data type | API Key |
| -------------------- | --------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------- |
| Ad spend | Total amount spent during the reporting period, excluding VAT. Defaults to 0 when Kakao returns no value. | Currency | `metrics.spending` |
| Ad spend (incl. VAT) | Ad spend with Korean VAT applied (spend × 1.1). | Currency | *Adriel-computed from `metrics.spending`* |
| CPA | Cost per action (spend ÷ conversions). | Currency | *Adriel-computed* |
| CPR | Cost per result — spend divided by the resolved result count. | Currency | *Adriel-computed* |
**Currency**
Kakao Keyword Ads reports spend in Korean won (KRW); no other currency is available from the API. When the ad account currency differs from the workspace currency, costs are automatically converted using the current day's exchange rate.
### Conversion performance
| Metric | Description | Data type | API Key |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------- |
| Conversions | Attributed actions matching the defined conversion events. Defaults to "Purchase" when no specific event is set. | Number | *Adriel-resolved from imported conversion events* |
| Conversion value | Monetary value of attributed conversions (7-day purchase window). | Currency | `metrics.convPurchaseP7d` |
| Revenue | Alias for conversion value — monetary value of attributed conversions. | Currency | `metrics.convPurchaseP7d` |
| ROAS | Return on ad spend (conversion value ÷ spend). | Ratio | *Adriel-computed* |
| CVR | Conversion rate (conversions ÷ clicks × 100%). | Percentage | *Adriel-computed* |
### Custom conversion events
Each conversion event tracked in the ad account is imported automatically. For every imported event, these metrics are auto-generated:
| Pattern | Description | Data type | API Key |
| --------------------------------------------------- | ---------------------------------------- | ---------- | ------------------------------------------------- |
| `Kakao Keyword Ads: [event_name]` | Count of that event. | Number | *Resolved from the event name in the Kakao setup* |
| `Kakao Keyword Ads: [event_name]: Conversion value` | Monetary value attributed to that event. | Currency | *Resolved* |
| `Kakao Keyword Ads: [event_name]: CPA` | Cost per action (spend ÷ count). | Currency | *Adriel-computed* |
| `Kakao Keyword Ads: [event_name]: ROAS` | Return on ad spend (value ÷ spend). | Ratio | *Adriel-computed* |
| `Kakao Keyword Ads: [event_name]: CVR` | Conversion rate (count ÷ clicks × 100%). | Percentage | *Adriel-computed* |
Custom event metrics only appear in dashboards when the underlying event is active in the ad account. Events are imported with 1-day and 7-day window variants (for example `add_to_cart_1D`, `add_to_cart_7D`, `app_install_1D`, `completed_registration_7D`, `purchase`, `purchase_1D`, `purchase_7D`, `sign_up_1D`, `sign_up_7D`).
### Budget & schedule
| Metric | Description | Data type | API Key |
| --------------- | --------------------------------------------------- | --------- | -------------------------------------- |
| Daily budget | Daily budget set on the campaign or ad set. | Currency | `dailyBudgetAmount` |
| Lifetime budget | Total budget allocated for the campaign's lifetime. | Currency | *Adriel-resolved* |
| Bid cap | Bid cap set on the ad set or campaign. | Currency | *Adriel-resolved* |
| Starts | Campaign start date. | Date | *Resolved from campaign configuration* |
| Ends | Campaign end date. | Date | *Resolved from campaign configuration* |
| Days remaining | Days between today and the campaign end date. | Number | *Adriel-computed* |
### Campaign structure metadata
| Metric | Description | Data type | API Key |
| --------------- | --------------------------------------------------------------------------------- | --------- | -------------------------------------- |
| Ad account name | Name of the ad account. | Text | `name` |
| Campaign name | Campaign name. | Text | `name` |
| Ad set name | Ad group (광고그룹) name, mapped to ad set. | Text | `name` |
| Ad name | Ad (creative) name. | Text | `creative.name` |
| Keyword name | Keyword text (search campaigns only). | Text | `text` |
| Status | Campaign, ad set, or ad status (for example running, paused, deleted, in review). | Text | `status` |
| Objective | Campaign objective. | Text | *Adriel-resolved* |
| Bid Strategy | Bid strategy set on the ad set or campaign. | Text | *Adriel-resolved* |
| Creative type | Type of the ad creative. | Text | *Resolved from creative configuration* |
| Creative URL | Destination URL of the ad. | URL | *Resolved from creative configuration* |
| Channel | Constant grouping label used for cross-connector rollup. | Text | *Constant value* |
### UTM tracking
| Metric | Description | Data type | API Key |
| ------------ | -------------------------------- | --------- | ---------------------------------------------- |
| UTM Source | Parsed `utm_source` parameter. | Text | *Adriel-parsed from ad config and landing URL* |
| UTM Medium | Parsed `utm_medium` parameter. | Text | *Adriel-parsed* |
| UTM Campaign | Parsed `utm_campaign` parameter. | Text | *Adriel-parsed* |
| UTM Content | Parsed `utm_content` parameter. | Text | *Adriel-parsed* |
| UTM Term | Parsed `utm_term` parameter. | Text | *Adriel-parsed* |
## Breakdowns
### Ad hierarchy
| Breakdown | Description | API Key |
| ----------------- | ---------------------------------------------- | ---------- |
| Ad account | Group by ad account. | `name` |
| Campaign | Group by campaign. | `campaign` |
| Ad set (ad group) | Group by ad group (광고그룹), mapped to ad set. | `adSet` |
| Ad | Group by ad (creative). | `ad` |
| Keyword | Group by keyword ID (search campaigns only). | `keyword` |
| Keyword text | Group by keyword text (search campaigns only). | `text` |
### Segmentation
| Breakdown | Description | API Key |
| ------------- | ---------------------------------------------------------------------------------------- | ----------- |
| Device target | Device segmentation, available at ad-account level. | `DEVICE` |
| Hour of day | Hourly segmentation. Subject to a 62-day lookback cap — see [Limitations](#limitations). | `HOUR` |
| Placement | Platform / placement segmentation. | `PLACEMENT` |
Only one segmentation breakdown can be applied per query. When none is applied, Kakao returns daily totals with no segmentation.
### Time & date grouping
Kakao returns daily records; Adriel groups them into these views for reporting. All time-grouping breakdowns are Adriel-side aggregations of the same underlying daily data.
| Breakdown | Description |
| -------------------------- | ------------------------------------------------------------ |
| Auto Time Breakdown | Automatically picks the best granularity for the date range. |
| Daily | Split reports by day. |
| Weekly (Start: Mon) | Split reports by week, starting Monday. |
| Weekly (Start: Sun) | Split reports by week, starting Sunday. |
| Week Date Breakdown | Group by day of the week (for example Monday). |
| Week Number Breakdown (W#) | Split by week number in the year. |
| Monthly | Split reports by calendar month. |
| Quarterly | Split reports by calendar quarter. |
| Yearly | Split reports by calendar year. |
### Creative analysis
Adriel post-processes ad creatives to generate this breakdown.
| Breakdown | Description |
| -------------- | ----------------------------------------------- |
| Creative image | Auto-clusters visually similar creative images. |
### UTM tracking
UTM values are parsed by Adriel, not returned by Kakao. Adriel reads the UTM query parameters from each ad's configuration and landing URL and exposes them for grouping.
| Breakdown | Description |
| ------------ | ------------------------------- |
| UTM Source | Group by parsed `utm_source`. |
| UTM Medium | Group by parsed `utm_medium`. |
| UTM Campaign | Group by parsed `utm_campaign`. |
| UTM Content | Group by parsed `utm_content`. |
| UTM Term | Group by parsed `utm_term`. |
## Limitations
Based on the current connector, Kakao Keyword Ads has the following limits:
* **62-day cap on hourly segmentation** — when the hourly breakdown is requested, Kakao enforces a 62-day maximum lookback to keep response sizes manageable. Daily-granularity queries can go further back, subject to the date range limits above.
* **12-month data guarantee** — access to the most recent 12 months of data is guaranteed. Older data relies on a legacy cache and may be incomplete or unavailable.
* **Per-campaign query fan-out** — Kakao's API does not accept aggregate queries spanning all campaigns at once. Queries are fanned out per campaign (or per ad set at deeper levels) and merged transparently, and ad-account-level requests are substituted with campaign-level aggregation.
* **One segmentation breakdown per query** — device, hour, and placement segmentation are mutually exclusive within a single query.
* **KRW only** — Kakao reports spend in Korean won; no other currency option is available from the API. Values in other workspace currencies are converted by Adriel.
## API references
* Kakao Business Keyword Ad API — base URL `https://api.keywordad.kakao.com/openapi/v1` (v1)
* [Kakao for Business — Keyword Ad](https://business.kakao.com/info/keywordad/)
* [Kakao Developers — Kakao Login (OAuth 2.0)](https://developers.kakao.com/docs/latest/en/kakaologin/common)
* [Kakao Pixel & SDK](https://business.kakao.com/info/kakaopixelnsdk/)
## See also
* [Kakao Keyword Ads how-to (paired)](/data-sources/g-n/kakao-keyword-ads/how-to-connect) — step-by-step setup guide
* [Kakao Moment data reference](/data-sources/g-n/kakao-moment/data-reference) — display and message ads on KakaoTalk and Daum
* [Naver Search Ads data reference](/data-sources/g-n/naver-search-ads/data-reference) — a comparable Korean search-keyword platform