> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iqrush.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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](/developers/guides/10-stability).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.