> ## 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 SmartNews Ads data source in Adriel.

## Introduction

SmartNews Ads is the paid advertising platform for SmartNews, the news aggregation app with a large audience in Japan and the United States. Advertisers run campaigns across the SmartNews feed, and the connector imports the resulting structure and performance data through the SmartNews Insights API, which delivers reports as streamed CSV. The connector is currently in **beta**.

As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration.

To connect this data source, see [How to connect SmartNews Ads to Adriel](/data-sources/o-z/smartnews-ads/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers ad accounts, campaigns, ad groups, and ads. It refreshes twice daily at **4:00 PM and 5:00 AM (UTC)**.

### Reports data

Reports include daily performance metrics for campaigns, ad groups, and ads.

**Real-time.** Report data is fetched from SmartNews on demand when a dashboard loads, so the latest values are always visible. Reports are always queried live — this connector is not cache-only. On top of that, scheduled cache refreshes keep historical data consistent across multiple time windows.

**Refresh schedule.** Reports refresh on three overlapping schedules:

* **5:00 PM UTC daily** — syncs the last **9 days** for ad account, campaign, ad group, and ad
* **11:40 PM and 6:40 AM UTC daily** — syncs the last **3 days** for ad account, campaign, ad group, and ad
* **7:30 AM UTC on the 1st and 15th of each month** — syncs the last **30 days** for ad account, campaign, ad group, and ad

## Architecture levels

Ad account → Campaign → Ad group → Ad

<Note>
  SmartNews does not support ad-account-level reports directly. Adriel queries at the campaign level and aggregates the results up to the ad account, so ad account totals are always available in dashboards.
</Note>

## Date range limits

To keep query sizes manageable, the connector enforces these maximum look-back windows per date grouping:

| Grouping | Max range |
| -------- | --------- |
| Daily    | 93 days   |
| Weekly   | 1 year    |
| Monthly  | 2 years   |

## Metrics

<Note>
  **How to read the columns**
  **Data type** uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
  **API Key** in code style like `viewable_impression` is the literal SmartNews CSV / API field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field.
</Note>

### Delivery & clicks

| Metric                | Description                                                    | Data type  | API Key                 |
| --------------------- | -------------------------------------------------------------- | ---------- | ----------------------- |
| Impressions           | Viewable impressions — times the ads were shown in view.       | Number     | `viewable_impression`   |
| Clicks                | Total clicks on the ads.                                       | Number     | `click`                 |
| CTR                   | Click-through rate.                                            | Percentage | `ctr`                   |
| Reach                 | Unique users who saw the ads at least once (CSV reports only). | Number     | `reach`                 |
| Frequency             | Average impressions per reached user (CSV reports only).       | Ratio      | `frequency`             |
| Video views           | Total video views.                                             | Number     | `video_views`           |
| Video views at 25%    | Video views reaching 25% completion.                           | Number     | `video_views_p25`       |
| Video views at 50%    | Video views reaching 50% completion.                           | Number     | `video_views_p50`       |
| Video views at 75%    | Video views reaching 75% completion.                           | Number     | `video_views_p75`       |
| Video views at 95%    | Video views reaching 95% completion.                           | Number     | `video_views_p95`       |
| Completed video views | Fully completed video views.                                   | Number     | `video_views_completed` |

### Cost & spend

<Note>
  Currency values are reported in each ad account's configured currency. If it differs from the workspace currency, values are converted using the current day's exchange rate.
</Note>

| Metric                  | Description                                                                      | Data type | API Key                     |
| ----------------------- | -------------------------------------------------------------------------------- | --------- | --------------------------- |
| Ad spend                | Total amount spent during the reporting period.                                  | Currency  | `budget_spent`              |
| CPC                     | Cost per click.                                                                  | Currency  | `cpc`                       |
| CPM                     | Cost per thousand impressions.                                                   | Currency  | `cpm`                       |
| Lifetime spent          | Total amount spent over the campaign's lifetime.                                 | Currency  | `lifetime_spent`            |
| Spent before this month | Amount spent prior to the current month.                                         | Currency  | `spent_before_this_month`   |
| Daily budget            | Configured daily budget on the campaign (converted from micro-units).            | Currency  | `daily_budget_amount_micro` |
| Lifetime budget         | Configured lifetime spending limit on the campaign (converted from micro-units). | Currency  | `spending_limit_micro`      |
| Bid strategy            | Configured bid strategy (Manual Bidding, Highest Volume, or Target Cost).        | Text      | `bid_strategy`              |

<Note>
  Budget metrics are parsed from campaign-level entities only. Ad group budgets are not yet available.
</Note>

### Conversions & value

Conversion metrics are generated per conversion event. For each event, a count, a conversion rate, and a cost-per-action metric are produced.

| Metric                | Description                                      | Data type  | API Key         |
| --------------------- | ------------------------------------------------ | ---------- | --------------- |
| Conversions           | Attributed conversion actions for a given event. | Number     | `count_[event]` |
| Conversion rate (CVR) | Conversions divided by clicks, per event.        | Percentage | `cvr_[event]`   |
| Cost per action (CPA) | Spend divided by conversions, per event.         | Currency   | `cpa_[event]`   |

**Available conversion events:** `purchase`, `add_to_cart`, `initiate_checkout`, `submit_form`, `complete_registration`, `sign_up`, `view_content`, `install`, `d1_retention`, `lead`.

<Note>
  SmartNews declares a broader catalog of conversion events, but only the events listed above are currently populated in Adriel. See [Limitations](#limitations).
</Note>

## Breakdowns

### Standard hierarchy

| Breakdown  | Description                                           | API Key                     |
| ---------- | ----------------------------------------------------- | --------------------------- |
| Ad account | Group by ad account (aggregated from campaign level). | *Aggregated from campaigns* |
| Campaign   | Group by campaign.                                    | `campaign_id`               |
| Ad group   | Group by ad group.                                    | `ad_group_id`               |
| Ad         | Group by ad.                                          | `ad_id`                     |

### Demographics & geography

| Breakdown | Description           | API Key  |
| --------- | --------------------- | -------- |
| Age       | Audience age bracket. | `age`    |
| Gender    | Audience gender.      | `gender` |
| Location  | Audience city.        | `city`   |

### Device & platform

| Breakdown     | Description                                          | API Key       |
| ------------- | ---------------------------------------------------- | ------------- |
| OS            | Operating system on which the impression was served. | `os`          |
| Device target | Targeted device type.                                | `device_type` |

### Creative content

<Note>
  Creative breakdowns are derived from architecture metadata rather than report segmentation, so they are available for grouping but not as live report breakdowns.
</Note>

| Breakdown            | Description                    | API Key               |
| -------------------- | ------------------------------ | --------------------- |
| Creative title       | Group by creative headline.    | `creativeTitle`       |
| Creative description | Group by creative description. | `creativeDescription` |

### Time grouping

<Note>
  SmartNews returns daily records; Adriel aggregates them into these views on demand.
</Note>

| Breakdown | Description                      |
| --------- | -------------------------------- |
| Daily     | Split reports by day.            |
| Weekly    | Split reports by week.           |
| Monthly   | Split reports by calendar month. |

### Overview

<Note>
  These grouping options are added by Adriel for reporting and cross-connector rollup.
</Note>

| Breakdown   | Description                                                                                              |
| ----------- | -------------------------------------------------------------------------------------------------------- |
| Channel     | Constant grouping label — for SmartNews Ads this is always "smartNews". Used for cross-connector rollup. |
| No grouping | Do not break down; return one aggregated row.                                                            |

## Limitations

* **Beta connector** — SmartNews Ads is in beta; coverage and behavior may change.
* **Conversion event coverage** — Adriel currently populates 10 conversion events (listed above). SmartNews declares additional events at the API layer that are not yet mapped and will not appear even if the platform returns them.
* **No ad-account-level reports** — the SmartNews API does not support ad-account-level reports; Adriel aggregates campaign-level data to produce ad account totals.
* **Reach and frequency are CSV-only** — these metrics are available only from the CSV report format.
* **Ad group budgets unavailable** — budgets are parsed from campaign-level entities only.
* **Catalog creative media** — for catalog carousel and catalog image formats, only text fields (headline, sponsored name) are available; images and videos are not fetched.

## API references

* [SmartNews Ads API documentation](https://developers.smartnews.com/)&#x20;

## See also

* [How to connect SmartNews Ads to Adriel](/data-sources/o-z/smartnews-ads/how-to-connect) (paired how-to)
* [Meta Ads data reference](/data-sources/g-n/meta-ads/data-reference) — comparable ad-platform data reference