Read a metric over time

Retrieve metric series across selected completed runs. MCP tool: get_metric_timeseries. Operation: read. Uses the authorized connection; no project or content changes are made by this tool.

Parameters

Name	Type	Required	Default	Meaning and accepted values
`project_id`	string	Yes	`Required`	Project ID from list_projects. Select the project in the intended workspace and environment.
`metric_family`	string	Yes	`Required`	Select citation, mention, or sentiment history. This choice determines the permitted metric and reporting unit.
`metric`	string or null	No	`null`	citation accepts share or coverage; mention accepts coverage; sentiment accepts net, positive, or negative. Omission selects share, coverage, or net respectively.
`aggregation_level`	string or null	No	`null`	citation accepts domain or url; mention and sentiment use bundle. Omission selects domain for citation and bundle for the other families.
`entities`	string[] or null	No	`null`	Restrict mention or sentiment history to the requested brand/entity labels. Use labels actually measured in the project.
`domains`	string[] or null	No	`null`	Restrict citation history to selected source keys. Use returned domain names or, for URL history, exact page URLs.
`top_n`	integer or null	No	`null`	Series-selection limit when entities and domains are omitted. An explicit entity or source selection takes precedence; this is not the number of runs or points.
`run_ids`	string[] or null	No	`null`	Select runs from this project for the history window. Omit to use the available window; inspect n_runs and truncated in the response.

Family defaults: citation/share/domain; mention/coverage/bundle; sentiment/net/bundle. Default top_n is 6.

Example call

Replace ID placeholders and example selections with values from your account. This is the params object for MCP tools/call.

{
  "name": "get_metric_timeseries",
  "arguments": {
    "project_id": "PROJECT_ID",
    "metric_family": "citation",
    "metric": "share",
    "aggregation_level": "domain",
    "domains": [
      "colorescience.com"
    ]
  }
}

Read the response

Read data.series, where each series has a key and points. Each point carries run_id, completed_at, and estimate. The envelope run_id can be an array. Preserve the interval on each point.

Fields to use

These selected fields explain the example and the result to preserve. Field presence depends on the response; this is not a complete response schema.

Field	Meaning and use
`data.n_runs`	Runs included in the returned history.
`data.n_runs_total`	Available run count reported before window truncation.
`data.truncated`	Whether the offered history window was shortened.
`data.rows[].series`	Source or entity key for this history row.
`data.rows[].x`	Measurement completion timestamp used for the row’s time position.
`data.rows[].estimate`	History estimate with interval and row quality. Keep the endpoint’s returned scale when comparing points.

Response example

Selected fields from an observed IQRush Dev response. Lists are shortened and project/run IDs are placeholders. Omitted fields remain available in the actual response.

{
  "data_ready": true,
  "data": {
    "metric_family": "citation",
    "metric": "share",
    "aggregation_level": "domain",
    "n_runs": 2,
    "n_runs_total": 2,
    "truncated": false,
    "rows": [
      {
        "series": "colorescience.com",
        "x": "2026-09-19T22:25:41.958885+00:00",
        "estimate": {
          "value": 3.35375,
          "ci": {
            "lower": 2.1563341811947696,
            "upper": 4.55116581880523,
            "level": 0.95
          },
          "n": 238,
          "stability": "stable",
          "stability_n": 238
        }
      }
    ]
  }
}

Read the actual returned scope, counts, and interval levels before interpreting these fields.

Important behavior

Use explicit run_ids for repeatable reports. The MCP tool has no filters argument in this edition. A single run cannot establish a trend. Check tool and payload errors before using the result. Response handling explains estimates and empty results; errors and recovery covers invalid requests and temporary failures. HTTP equivalent: Read a metric over time. HTTP parameters and defaults can differ.

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

Read a metric over time

Parameters

Example call

Read the response

Fields to use

Response example

Important behavior

​Parameters

​Example call

​Read the response

​Fields to use

​Response example

​Important behavior

Parameters

Example call

Read the response

Fields to use

Response example

Important behavior