Version 1 contract

Give every total its context

Use analyze_report for one report with 1–50 metric comparisons. Required fields are explicit: use null for an unknown side value or metadata field. Unknowns never default to zero or agreement. See the complete example.

Report fields

schema_version is 1.0.0. Supply a neutral report_label, ISO window_start and window_end with offsets, an IANA reporting_timezone, and boundary_convention set to start_inclusive_end_exclusive. End must be later than start. Declare any shared_metadata_applied to both sides; the service never fills missing side values from that list.

Metrics and evidence

Every metric needs a stable lowercase metric_id, name, source and output labels; each side has a decimal-string or null value, unit, currency, aggregation, window, timezone, boundary convention, filters summary, attribution rule, refresh cutoff, definition ID and definition evidence. Currency totals require an explicit three-letter currency code on each side; other units use null. Different currencies are never converted.

Evidence and report approval have status (declared, unverified, unknown or approved), a neutral evidence label, and approver_role. Unknown information is null. Approved evidence requires both a label and role; the service cannot authenticate that declaration. Declared definition evidence supports only a comparison of the supplied assertions. Unverified or unknown definition evidence prevents a reconciled match.

Choose tolerance explicitly

Supply choice: explicit, nonnegative decimal strings for absolute and relative tolerance, a unit matching both sides, and a neutral supplied_by role. If you want exact comparison, explicitly choose absolute 0 and relative 0. The assistant must ask before choosing it for you.

signed_difference = output − source
absolute_difference = abs(signed_difference)
relative_difference = absolute_difference / abs(source)
allowed_difference = max(absolute_tolerance, relative_tolerance × abs(source))
within tolerance when absolute_difference ≤ allowed_difference

A relative tolerance of 0.005 means 0.5 percent. A zero source gives a null relative difference with a zero-baseline reason; only absolute tolerance determines the match. Negative adjustments are preserved. Relative output is rounded to 100 significant digits; bounded tolerance decisions use exact decimals.

Supported scope and limits

Version one computes additive count, currency and decimal totals. Counts must be integers. Rates, percentages, ratios, distinct counts and averages return unsupported_metric. No event timestamps are inferred, aggregate timezones shifted, joins diagnosed or unrestricted files ingested.

Labels are plain text up to 80 characters. Decimal strings allow 24 integer and 12 fractional digits, with an optional minus sign. Unknown fields and executable syntax are rejected. Request body ceiling: 64 KiB. Response ceiling: 256 KiB. Per hosting isolate: 30 requests per minute per client address, 120 total requests per minute and 8 concurrent requests. These are local safeguards, not a global quota guarantee. Overload returns safe retry guidance.

Read the result

Statuses are matched_within_tolerance, discrepancy, not_comparable, evidence_missing and unsupported_metric. A comparable difference beyond tolerance is blocking. Incompatibility, missing evidence and unsupported measures need resolution. A limited match is informational. Each finding includes evidence field references, rule, calculation inputs, observed result, next check and limitations. The acceptance checklist cites those finding IDs and leaves approval with the reporting owner.