Metric definitions and the figures that are easy to misread

The Convultra API and MCP server are in Beta. Four figures cause nearly every support question about them. GET /meta/metrics (get_metric_definitions) returns every definition programmatically, so a script or an assistant can read them rather than assume. This page is the human version.

Conversion rate is conversions divided by visitors, never sessions

A visitor is unique by first-party id over the period, with bots and excluded IPs removed before counting. A tool that divides by sessions will always show Convultra lower, and the gap is not an error in either.

The one exception, stated plainly: conv_rate on get_breakdown rows is per session, because those rows count sessions and visitors is null there. Do not compare a breakdown rate with an overview rate.

null is not zero

A null spend, ROAS or CPA means the integration is not connected. Unknown spend and zero spend are different answers, and a ROAS built on the second is a lie. Every one of those fields comes with a sibling explaining itself: spend_unavailable_reason when no cost has been synced, spend_omitted_reason when the credential lacks spend:read or the granularity cannot carry it. Read the reason and report “unavailable”, not “0”.

The same rule holds throughout: null means “cannot tell you”, 0 means “nothing happened”. A null revenue on a breakdown row means that dimension cannot report revenue. A missing row in a timeseries would mean a bug, which is why there are never missing rows, only zeros.

AI referrals count in every total; AI crawlers count in none

An AI referral is a human who clicked a link inside ChatGPT, Claude, Perplexity or Gemini. It is a real session with real revenue, and it is already inside the overview’s visitors, conversions and revenue. Adding get_ai_referrals figures to a total double-counts.

An AI crawler is GPTBot or ClaudeBot fetching pages for indexing or training. It is a bot, filtered out at ingest, and it appears in no traffic, conversion or revenue figure anywhere. get_filtered_out is the only place it is reported, and within that response total_bot_events and total_ai_crawler_events overlap, so do not add those either.

Rates are ratios between 0 and 1

conv_rate, bounce_rate, delivery_rate, recovery_rate, drop_off_rate, attributed_share and share are ratios to 4 decimal places. The field name says _rate or _share, so the value is never pre-multiplied by 100. Money is rounded to 2 decimal places. Percentage changes in get_overview’s change block are also ratios, and are null, not Infinity, not 0, when the earlier figure was zero.

Definitions

Convultra is the source of truth for its own numbers. These are the same definitions the dashboard shows in its tooltips and the email report uses.

Recovery and attribution denominators

Two more figures need their denominators stated:

• recovery_rate from get_recovery is the recovered share of attributed conversions (those with a captured click id), not of all conversions.
• attributed_share from get_attribution is the share of total conversions that carry at least one ad click. The platform rows describe only that share; organic, direct and email conversions are in the total and in no platform row.

Before you compare with another tool

1. Call get_metric_definitions and confirm the denominator.
2. Check meta.range for the timezone actually used. See Date ranges and timezones.
3. Call get_tracking_health. A tracking outage and a bad week look identical in the numbers.
4. Check whether the other tool counts view-through, or dates conversions by click rather than by event.

See API operations for the per-operation traps.