How do I meter AI agent API usage with signed per-call usage records for invoicing, separate from human traffic?

What should I check, step by step?

1. Create a meter per billable action (for example agent.api_call, agent.rows_exported) with a clear unit and aggregation (sum of calls, sum of rows). Do not reuse human analytics events.

2. Identify the payer before you count: map each agent credential id to a customer (tenant or contract id). Reject or park calls that authenticate but have no billing mapping.
3. On each billable agent response (2xx you intend to charge), emit one usage event with: customer_id, credential_id, meter/event_name, value, timestamp, and a unique idempotency key (request id). Stripe meter events recommend a UUID-like identifier so retries do not double-bill.
4. Seal evidence: hash the canonical event (or a daily batch) and record it with record_ai_run or your own signed usage receipt so neither side can silently rewrite the period's totals later. Keep the full event store yourself; the seal holds hashes and counts.
5. Keep humans out: middleware that meters must require an agent credential (or explicit agent API key). Session-cookie browser traffic must not increment agent meters.
6. At invoice time, aggregate by customer and meter for the closed period, attach the sealed batch id or receipt ids as supporting evidence, and give the customer verify_ai_run / ledger_verify links for the seals.
7. Handle disputes with the raw events: show the idempotency keys and credential ids for contested lines. If you refund, append a negative adjustment event; do not edit history.
8. Separate hard rate limits from billing meters. A 429 means try later; a usage record means this successful call is on the next invoice.

Why must AI agent API usage meters exclude human page views?

CDN and product analytics count humans and bots together unless you filter. Invoices for agent API access need a counter that only advances when a verified agent credential (or your agent API key) passed auth on a billable route.

• OpenAI's organization usage and costs Admin APIs group spend by api_key_id, project_id and related dimensions — the same idea: attribute usage to the key or agent that caused it, not to a shared IP.
• If an agent and a human share a NAT, only the credentialed /api/* calls should land on the agent invoice. Browser document requests stay unmetered for this product (or on a different human plan).

What fields belong in a signed per-call AI agent usage record for invoicing?

Minimum fields: event_name (meter), customer_id, agent credential id, value (integer units), timestamp, idempotency key, route or operation id. Optional: model or tool name, bytes, row count, response class/tier.

• Stripe Billing Meters take high-throughput meter_events with event_name, payload mapped to a customer, a numeric value, and an identifier for deduplication — use the same shape even if you settle outside Stripe.
• Sign or hash-seal at the end of the call (or in a flush every N seconds). A CSV exported a week later without a seal is weaker evidence in a dispute than a receipt whose hash was fixed when the call finished.

How do I turn sealed AI agent usage records into an invoice a customer can dispute?

Close the period, sum events by meter and customer, and generate line items (your invoicing system, Stripe subscription invoices fed by meters, or Rightshold's usage-based invoice helper for agent services). Attach the sealed batch receipt ids.

• Let the customer recompute: give them the event export (or hashes) plus verify_ai_run on the seal. ledger_verify checks the chain the seal sits in. Agreement on the hash ends most "we never called that" arguments.
• Do not treat x402 payment at request time as a substitute for period invoices when your contract is monthly prepaid or postpaid usage — pay-per-call and monthly true-up are different products; pick one primary path per route.