Operational reports

Operational reports are for decisions and investigations, not only dashboard display.

This page defines concrete report semantics across the current Ops report surfaces.

Report surfaces and purpose

Surface	Core question	Primary entities
usage facts	what happened in product behavior	events
pricing decisions	how facts became billable outcomes	ratings, rated records
funding and settlement	how charges were funded and settled	allocations
finance aggregate	what invoice totals look like over time	revenue report

Scope and access rules

• Ops report endpoints are on /mgt/v1/ops/*.
• Account-scoped reads require a billing-account context.
• If caller is not cross-account capable, queried billing_account_id must match the caller context, otherwise request is rejected.
• If caller is cross-account capable, you can target another billing_account_id explicitly.

Time-basis discipline

Always document which timestamp basis is used in a query:

• event time (occurred_at)
• rating time (rated_at)
• allocation decision time (decided_at)
• settlement completion time (settled_at)
• invoice time basis (paid_at, finalized_at, period_start, or period_end)

Mixing bases causes false incident conclusions.

Pagination and sorting contract

• Page size is bounded; default is 50, maximum is 200.
• Cursor is coupled with sort_by and sort_order.
• Reuse cursor only with the same sort configuration that produced it.
• For stable pagination, do not change filters mid-stream.

Default sort behavior by surface

Surface	Default sort_by	Default sort_order
events	occurred_at	desc
ratings	rated_at	desc
rated records	created_at	desc
allocations	rated_at	desc

Query discipline

1. Fix scope first: realm, billing account, and time window.
2. Keep one time basis per query set.
3. Keep sort basis and cursor basis aligned in paginated reads.
4. Add expansions only when needed: ratings.expand=rated_records, allocations.expand=rating or rating.rated_records.
5. Record ids and exact filters used in every ticket note.

Revenue report semantics

• Revenue report uses /ops/reports/revenue.
• Required input: time.from, time.to, time.granularity.
• Supported granularity: day, month.
• time_basis defaults to paid_at when omitted.
• If status filter is omitted, report defaults to paid invoices.
• Two aggregation modes exist:
  • Invoice aggregate mode: returns subtotal_minor, tax_minor, total_minor.
  • Invoice-line aggregate mode: used when grouping by line_kind / meter_code / catalog_price_id, or when line_kinds filter is provided. returns line_total_minor.

Investigation workflow

1. Start from disputed account, amount, and window.
2. Confirm source facts in events.
3. Confirm pricing decision in ratings and rated-record decomposition.
4. Confirm funding/settlement path in allocations.
5. Use revenue aggregates only as top-level confirmation, not as root cause source.

Quality checks

• Aggregates are explainable from rating/allocation facts.
• Late ratings and reversals are visible as explicit status/link changes.
• Operator/manual effects are distinguishable from normal purchase flows.
• Reconciliation differences (if used) are treated as diagnostic signals, then validated against rating/allocation evidence.

Verify

• For a sampled incident, event -> rating -> allocation chain is mutually consistent.
• Ticket evidence includes exact time basis, filters, ids, and cursor/sort settings.

Next

• Deep investigation chain: Rating traceability