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

# What does the Budget usage column show for Apple Ads campaigns?

> Budget usage (7d) in the Qonversion Apple Ads report is the share of a campaign's current daily budget spent over the last 7 complete UTC days. This page lists its bands, the details panel, every reason a reading can be unavailable, the CSV columns and who can see it.

**Budget usage (7d)** is a column of the Apple Ads report in the Qonversion dashboard. It shows the share of a campaign's current daily budget spent over the last 7 complete UTC days: 7-day spend divided by 7 × the current daily budget, as a percent. It does not depend on the report period you select, it exists only for campaigns (not ad groups or keywords), and a Country filter turns it off. A reading above 100% does not by itself mean a budget limit was broken.

## How is budget usage calculated?

Budget usage (full name **Budget usage (7d)**) = spend over the last 7 complete UTC days ÷ (7 × the campaign's current daily budget), shown as a percent.

* **Window.** The 7-day window always covers the 7 full UTC calendar days before today (UTC). Today is not included. The details panel shows the window's dates with the timezone "UTC".
* **Independent of the report period.** The reading does not change when you pick another report period. The column picker hint reads "Recent 7 full days, not the selected report period".
* **Current budget, not historical.** Spend is compared with the campaign's current daily budget, not with the budget that applied when the money was spent.
* **Daily budget only.** Budget usage uses the campaign's daily budget. If no daily budget has been recorded for a campaign, there is no reading and the reason is **No budget on record**.
* **Not a limit check.** A reading above 100% does not by itself mean a limit was broken, because Apple's daily budget is an average target over a month. The percentage says nothing about results or ROI.

## What do the budget usage bands mean?

Every reading falls into one of five bands:

| Band label | 7-day spend as a share of 7 × current daily budget |
| - | - |
| **No spend** | 7-day spend is exactly 0 |
| **Far below the budget** | Above 0% and below 10% |
| **Below the budget** | 10% up to but not including 80% |
| **Close to the budget** | 80% up to but not including 100% |
| **Above the budget** | 100% or more |

Band boundaries are exact: the comparison uses the unrounded ratio. A reading displayed as "9.9%" is **Far below the budget**, and one displayed as "79.9%" is **Below the budget**.

### What do the colors mean?

For active campaigns, color repeats the band:

| Band | Color |
| - | - |
| **Below the budget** | Green |
| **Far below the budget**, **Close to the budget** | Amber |
| **No spend**, **Above the budget** | Red |

Paused, ended or unknown-state campaigns are shown muted. The band is also named in words in the reading's details, so color is not the only signal.

### How is the percent rounded?

The cell shows the percent truncated (never rounded) to one decimal and drops a trailing ".0". For example, 99.96% shows as "99.9%", and any positive value under 0.1% shows as `<0.1%`, never 0%. The details panel shows the exact value with 6 decimals.

## What does the budget usage details panel show?

Clicking a reading opens **Budget usage (7d)**. It shows the band label and these rows:

| Row | What it shows |
| - | - |
| **Budget usage** | The exact percent |
| **Spend, last 7 full days** | Spend in the 7-day window |
| **Average daily spend** | Average daily spend in the window |
| **Current daily budget** | The campaign's current daily budget |
| **7-day budget** | 7 × current daily budget |
| **Window** | The window's dates · UTC |
| **Coverage** | "N of 7 days proven" |
| **Currency** | The currency of the reading |
| **Lifecycle** | Active, Paused, Ended or Unknown, plus "· budget changed" when it applies |
| **Budget history** | "Known from \[date]", only when that history starts inside the window |
| **Budget observed** | UTC timestamp |
| **Spend updated** | UTC timestamp |
| **Data sources** | The data sources of the reading |

### What does "What to check" recommend?

For an active campaign with a reading, **What to check** gives one hint:

| Band | Hint |
| - | - |
| **No spend**, **Far below the budget** | Check the campaign status, impressions and delivery. The Far below hint uses the same "No spend over the last 7 full days…" text. |
| **Close to the budget** | Review results and settings before changing the budget. |
| **Above the budget** | Review budget changes and how spend is distributed; this is not proof of a limit violation. |
| **Below the budget** | "No recommendation — this reading calls for no check." |

* **Budget changed.** If the daily budget changed during the 7-day window, the cell shows a **Budget changed** marker, and the details explain that the reading compares spend to the current budget value. That note replaces the band's hint in What to check: the percent uses the current value.
* **Budget history starts inside the window.** If the campaign is proven to have existed since the 7-day window began, but Qonversion's verified record of its budget starts later, inside the window, the reading still shows. The cell's tooltip says "Budget history is known from" followed by the date, and What to check says no recommendation is given yet because a budget change in the window can't be ruled out. A No spend reading still gets its delivery check.
* **Paused, ended or unknown-state campaigns.** The percent and band still show, but What to check gives no recommendation.

## Why does a campaign show a dash instead of a budget usage percent?

When a reading can't be computed, the cell shows a dash, never 0%. A dash does not mean the campaign spent nothing. Hovering the dash shows the reason, and clicking it opens details under **Why there is no reading**, with every applicable reason and the main one marked **Primary**. In CSV export, the `budget_usage_reason` column holds the code of the primary reason and is empty when the campaign has a reading.

The table lists every reason in priority order, with the code that appears in `budget_usage_reason`:

| Reason label | Code | What it means | What to do |
| - | - | - | - |
| **Not available at this level** | `unsupported_scope` | Never produced: budget usage is computed only for campaigns, and ad group and keyword rows show a dash with "Budget usage is available at the campaign level" instead. | — |
| **Not available with filters** | `filtered_scope_unsupported` | A Country filter is on. Budget usage always covers the whole campaign, so a Country filter turns it off for every campaign. The Apple Ads report lets you include countries only; excluding Country is not offered. | Remove the Country filter. |
| **Timezone unknown** | `timezone_unknown` | Never produced: the 7-day window is always in UTC. | — |
| **Unsupported currency** | `unsupported_currency` | The campaign's budget is not in USD and was not converted to USD. Because budget usage converts spend and budget to USD, a non-USD campaign gets a USD reading instead, or **Temporarily unavailable** if an exchange rate is missing. | — |
| **Mixed currencies** | `currency_mismatch` | The 7-day spend is in a different currency from the budget, or in more than one currency, and was not converted to USD; amounts in different currencies are never added together. Because budget usage converts spend and budget to USD, spend in another currency gets a USD reading instead, or **Temporarily unavailable** if an exchange rate is missing. | — |
| **No budget on record** | `budget_missing` | No daily budget has been recorded for the campaign. | — |
| **Budget unreadable** | `invalid_budget` | The budget is zero, negative or malformed. | — |
| **Spend unreadable** | `invalid_spend` | The spend data can't be read. | — |
| **Data changed mid-read** | `inconsistent_snapshot` | The data changed while the reading was computed. | The next read settles it; load the report again. |
| **Not enough history** | `insufficient_history` | The campaign started after the first day of the 7-day window, Qonversion can't show that the campaign existed on the window's first day (from Apple's campaign start date, Qonversion's first record of the campaign, or spend on that day), or Qonversion has no verified record of the campaign's budget. A campaign that did exist from the window's start but whose budget record starts later gets a reading instead, with the recommendation withheld. | It clears once the campaign has 7 full days of history. |
| **Incomplete spend data** | `incomplete_spend` | Fewer than 7 full days of spend are proven. | — |
| **Budget data stale** | `stale_budget` | The budget observation is older than 24 hours. | — |
| **Spend data stale** | `stale_spend` | The spend data is older than 36 hours or still catching up. | — |
| **Temporarily unavailable** | `source_unavailable` | A data source failed, an exchange rate needed to convert the campaign's spend or budget to USD is missing, or, on app-scoped projects, the campaign is not confirmed as belonging to the app. | — |

When several reasons apply, they are listed in a fixed order and the first is the primary one. The table above follows that order: `unsupported_scope`, `filtered_scope_unsupported`, `timezone_unknown`, `unsupported_currency`, `currency_mismatch`, `budget_missing`, `invalid_budget`, `invalid_spend`, `inconsistent_snapshot`, `insufficient_history`, `incomplete_spend`, `stale_budget`, `stale_spend`, `source_unavailable`.

## Where is budget usage available?

Budget usage is available only for campaigns:

* The **Budget usage** column appears only at the campaign level of the Apple Ads report. It is not part of the default table layout; add it from the **Columns** picker.
* On a campaign's own page, the reading sits next to its budget.
* Ad group and keyword rows show a dash ("Budget usage is available at the campaign level").
* The totals row shows a dash ("not additive across the report").
* Budget usage is not available in summary cards or charts.

## What currency is budget usage in?

Budget usage readings are in USD. Spend in another currency is converted to USD at each day's rate, and the current daily budget at today's rate. If a rate is missing, the campaign shows **Temporarily unavailable**.

## Which CSV columns does budget usage add?

When the **Budget usage** column is visible, CSV export of the Apple Ads report expands it into these twelve columns:

| CSV column |
| - |
| `budget_usage_percent` |
| `budget_usage_state` |
| `budget_usage_reason` |
| `budget_usage_window_start` |
| `budget_usage_window_end_exclusive` |
| `budget_usage_window_timezone` |
| `current_daily_budget` |
| `currency` |
| `spend_7d` |
| `budget_observed_at` |
| `spend_observed_at` |
| `budget_usage_algorithm_version` |

## Who can see budget usage?

Anyone who can open the Apple Ads report can see budget usage. It needs no extra permission and no campaign-management access.

Budget usage is available only in the Qonversion dashboard. There is no MCP tool or REST endpoint for 7-day budget usage per campaign.

## What is not supported?

* Budget usage for ad groups or keywords: it is available only for campaigns.
* Budget usage with a Country filter: every campaign then shows **Not available with filters**.
* Budget usage in the totals row, summary cards or charts.
* Summing, sorting or filtering by the **Budget usage** column.
* Budget usage for a report period you choose: the window is always the last 7 full UTC days.
* Comparison with the budget that applied when the money was spent: only the current daily budget is used.
* Budget usage through the Qonversion MCP server or REST API.

## Related pages

* [Read the Apple Ads report](/docs/apple-ads-report) explains all Apple Ads report columns, levels, filters and CSV export.
* [How fresh is Apple Ads data in Qonversion?](/docs/apple-ads-data-freshness) explains the "Updated …" indicator, data messages above the report table and spend history import.
* [Manage Apple Ads campaigns](/docs/apple-ads-manage-campaigns) explains how to change campaign daily budgets, bids and status from Qonversion.
* [Apple Ads via MCP](/docs/mcp-apple-ads) explains which Apple Ads data AI agents can read and change through the Qonversion MCP server.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.