> ## Documentation Index > Fetch the complete documentation index at: https://docs.adcontextprotocol.org/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 `buyer_campaign_ref`. A single request can span multiple accounts and campaigns. **Response Time**: \~1s. **Request Schema**: [`/schemas/latest/account/report-usage-request.json`](https://adcontextprotocol.org/schemas/latest/account/report-usage-request.json) **Response Schema**: [`/schemas/latest/account/report-usage-response.json`](https://adcontextprotocol.org/schemas/latest/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](/dist/docs/3.0.0-rc.2/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 | Signals: Yes | Pricing option selected from `pricing_options` in the [`get_signals`](/dist/docs/3.0.0-rc.2/signals/tasks/get_signals) response. The vendor uses this to verify the correct rate was applied. | | `buyer_campaign_ref` | string | No | Buyer's campaign reference (e.g., a `media_buy_id`). Used to group records by campaign. | | `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` | ## 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" }, "buyer_campaign_ref": "mb_spring_launch_001", "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 } ``` ### 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" }, "buyer_campaign_ref": "mb_spring_q1_001", "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" }, "buyer_campaign_ref": "mb_summer_preview_002", "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](/dist/docs/3.0.0-rc.2/accounts/tasks/sync_accounts) — Sync advertiser accounts with a seller before reporting * [Accounts Protocol](/dist/docs/3.0.0-rc.2/accounts/overview) — How account establishment and settlement fit together * [Accounts and agents](/dist/docs/3.0.0-rc.2/building/integration/accounts-and-agents) — Billing hierarchy and operator model