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

# Compare measurements without mistaking noise for change

> Use comparison tools when the question is whether a result changed. Two percentages, or two separate confidence intervals, are not a test of the difference.

Use comparison tools when the question is whether a result changed. Two percentages, or two separate confidence intervals, are not a test of the difference.

## Choose the comparison

| Question | Tool | Important limit |
| - | - | - |
| How does a metric move over several runs? | `get_metric_timeseries` | A trend requires at least two completed runs. |
| What are the largest increases or decreases? | `list_timeseries_movers` | A ranked movement list is descriptive. |
| Has the citation landscape shifted? | `screen_drift` | Cross-run change, not within-run convergence. |
| Which sources changed? | `attribute_drift` | Inspect each returned contrast and its scope. |
| Did a domain's citation share change between two runs? | `get_paired_contrast` | Domain-level citation `share` or `count` only in this edition. |
| What happened to ranks? | `get_rank_displacement` | Rank movement and share movement are different measures. |
| Which changes deserve investigation? | `get_significant_findings` | An exploratory screen; inspect correction metadata. |

## Make an explicit paired comparison

```json theme={null}
{
  "name": "get_paired_contrast",
  "arguments": {
    "project_id": "PROJECT_ID",
    "run_id": "NEWER_RUN_ID",
    "run_id_a": "OLDER_RUN_ID",
    "run_id_b": "NEWER_RUN_ID",
    "entity_or_domain": "colorescience.com",
    "score_family": "citation",
    "metric": "share"
  }
}
```

Set `run_id` to `run_id_b`. Both runs must belong to the project. Use a bare domain, not a page URL. For a within-run comparison, use `condition_a` and `condition_b`, such as two platform conditions, instead of the two run-ID arguments.

Read `data.contrast.value_a`, `value_b`, `diff`, `ci_diff`, and `significant`. The difference is B minus A. For share, a difference of `0.02` is 2 percentage points, not 2% relative growth.

`significant: false` does not prove that nothing changed. It means the comparison did not establish the claimed direction at the returned confidence level. Null contrast fields mean that the comparison could not be estimated; do not describe them as “no difference.”

## Select a reference run for drift tools

Omit `reference` for the previous-run default, or pass `{"type":"first_run"}` or `{"type":"specific_run","run_id":"REFERENCE_RUN_ID"}`. A bare string such as `previous_run` is not the JSON object format. Use a native object or its JSON-encoded string.

## Be careful with broad screening

`get_significant_findings` reports `correction` metadata. In this edition it does not correct for the full set of comparisons. A long list can contain chance findings. Treat it as a shortlist to investigate, retain `family_size`, and do not call every candidate a confirmed business change.

A confidence interval is required for a defensible estimate of change when the tool supplies one. Statistical evidence still needs business context: a detectable difference can be too small to matter, and an important question can remain uncertain.

Next: [Worked example](/developers/guides/17-worked-example).


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