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 Response Schema: /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	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

Request

{
  "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"
    }
  ]
}

{
  "accepted": 1
}

Creative usage — ad server with CPM pricing

Request

{
  "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"
    }
  ]
}

{
  "accepted": 1
}

Multi-account batch

A single request spanning two campaigns across two accounts:

{
  "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:

{
  "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 — Sync advertiser accounts with a seller before reporting
• Accounts Protocol — How account establishment and settlement fit together
• Accounts and agents — Billing hierarchy and operator model