> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-snap-format-preview-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# report_usage
> report_usage sends consumption data to AdCP vendor agents after campaign delivery — impressions served, signals queried, governance checks run — so vendors can track revenue and verify billing.
Reports how a vendor's service was consumed after campaign delivery. Called by orchestrators to inform a vendor agent (signals, governance, creative) what was used so the vendor can track earned revenue and verify billing.
Each usage record is self-contained — it carries its own `account` and `media_buy_id`. A single request can span multiple accounts and campaigns.
**Response Time**: \~1s.
**Request Schema**: [`/schemas/v3/account/report-usage-request.json`](https://adcontextprotocol.org/schemas/v3/account/report-usage-request.json)
**Response Schema**: [`/schemas/v3/account/report-usage-response.json`](https://adcontextprotocol.org/schemas/v3/account/report-usage-response.json)
## Request Parameters
| Parameter | Type | Required | Description |
| ------------------ | -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `idempotency_key` | string | Recommended | Client-generated unique key for this request (UUID recommended). If a request with the same key has already been accepted, the server returns the original response without re-processing. Prevents duplicate billing on retries. |
| `reporting_period` | object | Yes | `start` and `end` as ISO 8601 date-time in UTC. Applies to all records in the request. |
| `usage` | UsageRecord\[] | Yes | One or more usage records. |
### Usage Record Fields
Each record requires `account`, `vendor_cost`, and `currency`. Additional fields depend on the vendor type:
| Field | Type | Required | Description |
| ------------------------- | ------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account` | [AccountRef](/docs/building/integration/accounts-and-agents#account-references) | Yes | Account for this record — by `account_id` or `{ brand, operator }`. |
| `vendor_cost` | number | Yes | Amount owed to the vendor for this record, in `currency` |
| `currency` | string | Yes | ISO 4217 currency code |
| `pricing_option_id` | string | Vendor: Yes | Pricing option from the vendor's discovery response (`get_signals`, `list_creatives`, `list_content_standards`, `list_property_lists`) or execution response (`build_creative`). The vendor uses this to verify the correct rate was applied. |
| `impressions` | number | Signals: Yes | Impressions delivered |
| `media_spend` | number | percent\_of\_media: Yes | Media spend for percent-of-media cost verification |
| `signal_agent_segment_id` | string | Signals: Yes | Signal identifier from `get_signals` |
| `creative_id` | string | Creative: Yes | Creative identifier from `build_creative` or `list_creatives`. Links usage to a specific creative for billing verification. A `build_creative` variant leaf earns a `creative_id` only when trafficked/added to the library — discarded best-of-N or fan-out variants are never reported here; their charge is the inline per-leaf `vendor_cost` on the `build_creative` response (the authoritative record for untrafficked leaves). |
| `build_variant_id` | string | No | When the reported `creative_id` was promoted from a specific `build_creative` variant leaf but differs from that source id, carry the source `build_variant_id` for reconciliation. On the canonical path where `creative_id` is the kept `build_variant_id`, omit this field. |
| `property_list_id` | string | Property lists: Yes | Property list identifier from `list_property_lists`. Links usage to a specific property list for billing verification. |
## Response
| Field | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------ |
| `accepted` | Number of usage records successfully stored |
| `errors` | Validation errors for individual records. Partial acceptance is valid — accepted records are stored even when some fail. |
## Examples
### Signal usage — single campaign
```json Request theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
"reporting_period": {
"start": "2025-03-01T00:00:00Z",
"end": "2025-03-31T23:59:59Z"
},
"usage": [
{
"account": { "account_id": "acct_pinnacle_signals" },
"signal_agent_segment_id": "luxury_auto_intenders",
"pricing_option_id": "po_lux_auto_cpm",
"impressions": 4200000,
"media_spend": 21000.00,
"vendor_cost": 2100.00,
"currency": "USD"
}
]
}
```
```json Response theme={null}
{
"accepted": 1
}
```
### Creative usage — ad server with CPM pricing
```json Request theme={null}
{
"idempotency_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reporting_period": {
"start": "2026-03-01T00:00:00Z",
"end": "2026-03-31T23:59:59Z"
},
"usage": [
{
"account": { "account_id": "acct_acme_creative" },
"creative_id": "cr_88201",
"pricing_option_id": "po_video_cpm",
"impressions": 2400000,
"vendor_cost": 1200.00,
"currency": "USD"
}
]
}
```
```json Response theme={null}
{
"accepted": 1
}
```
### Multi-account batch
A single request spanning two campaigns across two accounts:
```json theme={null}
{
"idempotency_key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"reporting_period": {
"start": "2025-03-01T00:00:00Z",
"end": "2025-03-31T23:59:59Z"
},
"usage": [
{
"account": { "account_id": "acct_pinnacle_signals" },
"signal_agent_segment_id": "luxury_auto_intenders",
"pricing_option_id": "po_lux_auto_cpm",
"impressions": 2100000,
"vendor_cost": 1050.00,
"currency": "USD"
},
{
"account": { "account_id": "acct_nova" },
"signal_agent_segment_id": "eco_conscious_shoppers",
"pricing_option_id": "po_eco_cpm",
"impressions": 800000,
"vendor_cost": 400.00,
"currency": "USD"
}
]
}
```
### Partial acceptance
If some records fail validation, the response identifies how many were accepted:
```json theme={null}
{
"accepted": 1,
"errors": [
{
"code": "INVALID_PRICING_OPTION",
"message": "pricing_option_id 'po_unknown' does not exist on this account",
"field": "usage[1].pricing_option_id"
}
]
}
```
## Retry Safety
Always include `idempotency_key` in production usage. If a request times out or returns a network error, retry with the same key — the server will return the original result without double-counting.
Generate a fresh UUID per request, not per usage record. If you need to report additional records for the same period, submit a new request with a new key.
## Reporting cadence
Report at regular intervals — monthly at minimum. For campaigns with significant spend, weekly reporting gives vendor agents timely visibility into earned revenue.
Report upon campaign completion to close out the final period.
## Error Handling
| Error Code | Description | Resolution |
| ------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------- |
| `ACCOUNT_NOT_FOUND` | Account reference in a usage record not found or not accessible | Verify via `list_accounts`; re-run `sync_accounts` if needed |
| `INVALID_USAGE_DATA` | A usage record has missing or invalid fields | Check required fields for your vendor type |
| `INVALID_PRICING_OPTION` | `pricing_option_id` not found on this account | Verify `pricing_option_id` from the vendor's discovery response |
| `DUPLICATE_REQUEST` | Request with this `idempotency_key` was already accepted | Safe to ignore — original response is returned unchanged |
## Next Steps
* [sync\_accounts](/docs/accounts/tasks/sync_accounts) — Sync advertiser accounts with a seller before reporting
* [Accounts Protocol](/docs/accounts/overview) — How account establishment and settlement fit together
* [Accounts and agents](/docs/building/integration/accounts-and-agents) — Billing hierarchy and operator model