Handle responses, metrics, and units

Keep a metric’s value, confidence interval, scope, and availability together. That is what makes the result useful outside IQRush.

Measurement envelope

Many measurement tools return this structure. Project discovery, summaries, placement targets, co-mention networks, and Google data tools use other shapes, so do not require this envelope on every tool.

Field	How to use it
`project_id`, `run_id`	Identify the measured project and run. Time-series responses can carry several run IDs.
`schema_version`	Response schema label; not the MCP protocol version or a product release number.
`generated_at`	When the response was generated; not the run’s completion date.
`data_ready`	Whether data is available on this response path.
`brand_context`	Brand terms, bundles, and domain context.
`data`	Tool-specific results.
`error`	Error code, message, and optional details. Check this before using data.
`subject_summary`	Selection, returned counts, and unmeasured names when supplied.
`slice_summary`	A descriptive range across grouped rows; not a significance test.
`run_status_summary`	Available run-quality indicators. For a full stability check, request the stability tool.
`empty_reason`	Why a result has no rows, when provided.

Common response shapes

Tool	Where the main result lives
`get_citation_score`, `get_mention_score`, `get_sentiment`	`data.rows`
`get_results_stability`	`data`
`get_job_summary`	Top-level `metrics`
`get_executive_summary`	Top-level `headline_metrics` and breakdown fields
`get_placement_targets`	Top-level `targets`, `count`, `n_available`, `next_offset`
`get_comention_network`	Top-level `comentions` and optional `brand_rates`
`list_projects`, `list_runs`	Top-level `projects` or `runs`
`get_ga4_report`	Top-level `latest` and `history`

Estimate fields

Field	Meaning and display rule
`estimate.value`	Measured value. Preserve zero and null as different states.
`estimate.unit`	Scale to use for formatting, when supplied.
`estimate.ci.lower`, `estimate.ci.upper`	Confidence-interval bounds in the same scale as the estimate.
`estimate.ci.level`	Returned confidence level. For example, 0.95 is 95%; 0.975 is 97.5%. Preserve the level actually returned.
`estimate.n`	Count attached to this estimate. Its basis varies by metric; it is not a universal response denominator.
`estimate.n_responses`	Response count when the metric supplies it.
`estimate.stability_n`	Count associated with the returned row-quality assessment. It can differ from n.
`estimate.stability`	Returned row-quality label. Keep it separate from run convergence.
`estimate.basis`	Explanation of the estimate’s basis when supplied. Retain it with the value.

Fields vary by tool and availability. Display the returned confidence interval beside the estimate, with both bounds in the same unit as the value. Do not replace a missing interval with a zero-width interval, and do not invent an interval for a raw count or diagnostic that lacks one. Read unit when present. A proportion is 0–1 and a percent is 0–100. A count is a tally; a score is an index. Where a measurement row omits unit, follow the metric contract below. Do not guess a unit from the value’s size. Internal method identifiers are not explanatory labels for a user-facing report.

Comparison fields

Paired contrasts and source-change results use a comparison object rather than a single estimate. For a paired contrast it is data.contrast; for source-share changes it is each row’s share_diff.

Field	Meaning and display rule
`value_a`, `value_b`	The two values being compared. Retain which run or condition is A and which is B.
`diff`	B minus A. For run-change reports, B is the checkpoint and A is the reference.
`ci_diff`	Interval on the difference, including its returned confidence level. It is distinct from the two estimates’ individual intervals.
`significant`	Returned significance result; it does not establish causation or business importance.

For a proportion, multiplying the difference by 100 gives percentage points. A count difference stays a count, and a rank difference stays positions. Do not label every difference as percentage growth.

Metric meanings

The following scales describe the single-run measurement tools. Citation time-series values and bounds use percentages in this edition: a returned 3.35 means 3.35%, and its delta is in percentage points. Sentiment histories also use percentage-scale scores, with net sentiment allowed to be negative. Do not apply a single formatting rule to every endpoint with the same metric name.

Metric	Meaning	Typical measurement scale
Citation coverage	How often responses cite the selected domain or URL.	Proportion.
Citation share	The selected source’s share of citations in the measured scope.	Proportion.
Mention coverage	How often responses mention the selected entity.	Proportion.
Mention count	Number of mention occurrences represented by the selected result.	Count; use any returned interval.
Groundedness	How often the brand’s measured mention statements have citation support.	Proportion; check `estimate.basis`.
Sentiment classes	Positive, negative, or neutral rates for the scored mentions.	Proportion.
Net sentiment	The returned balance of positive and negative sentiment.	Signed score, typically −1 to 1.
Co-mention count	Statements in which both brands appear.	Count; not independent brand coverage.

For a single-platform set of six responses, appearing in three is 50% mention coverage. Repeating the brand several times in one response does not make that response count several times toward coverage. Citation coverage follows the same response-level idea for citations. Combined-platform results are not necessarily a pooled fraction of all counts. Use the returned estimate. For groundedness and co-mention rates, a separately returned pooled_rate can answer a different aggregation question. Do not replace the headline estimate with a ratio you calculate from its accompanying counts. The field n is not a universal sample-size denominator across every tool. Use the documented count fields, including n_responses where present, and retain the returned stability label. Do not recalculate that label from n.

Empty, zero, or unavailable

`empty_reason`	What it means for your report
`measured_zero`	A measured absence in this scope; retain any available uncertainty bound.
`not_measurable`	The metric could not be measured for this run. Read the unavailable reason.
`entity_not_indexed`	The requested name was not measured; this is not zero coverage.
`subject_selected_none`	Your subject selected no rows. Check the exact name or broaden the selection.
`filtered_or_degraded`	Read the attached warning before interpreting the result.
`run_not_ready`	The requested data is not ready yet.

A null value means unavailable, not zero. A zero estimate with a nonzero upper confidence bound is a bounded result, not proof the brand can never appear. Next: Decision-grade stability.

Get started

Connect securely

Read measurements

Build dependable integrations

Build reports

Report recipes

Reference

Session and discovery

Visibility measurements

Sources and evidence

Changes and trends

Google data

Pages and report planning

HTTP operations

Handle responses, metrics, and units

Measurement envelope

Common response shapes

Estimate fields

Comparison fields

Metric meanings

Empty, zero, or unavailable

​Measurement envelope

​Common response shapes

​Estimate fields

​Comparison fields

​Metric meanings

​Empty, zero, or unavailable

Measurement envelope

Common response shapes

Estimate fields

Comparison fields

Metric meanings

Empty, zero, or unavailable