Read a metric over time — HTTP

Retrieve metric series across selected completed runs. Method: GET Path: /projects/{project_id}/timeseries/metric Use the HTTP base for your authorized environment and an Authorization: Bearer header. See authentication and HTTP setup.

Parameters

This table covers the standard read profile. It excludes internal application routes and advanced analysis controls.

Name	Location	Type	Required	Default	Meaning
`project_id`	path	string	Yes	—	Project ID from list_projects. Select the project in the intended workspace and environment.
`metric_family`	query	string	Yes	—	Select citation, mention, or sentiment history. This choice determines the permitted metric and reporting unit.
`metric`	query	string	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`	query	string	No	`null`	citation accepts domain or url; mention and sentiment use bundle. Omission selects domain for citation and bundle for the other families.
`entities`	query	string	No	`null`	JSON-encoded array. Restrict mention or sentiment history to the requested brand/entity labels. Use labels actually measured in the project.
`domains`	query	string	No	`null`	JSON-encoded array. Restrict citation history to selected source keys. Use returned domain names or, for URL history, exact page URLs.
`top_n`	query	integer	No	`6`	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. Minimum 1. Maximum 200.
`run_ids`	query	string	No	`null`	JSON-encoded array. Select runs from this project for the history window. Omit to use the available window; inspect n_runs and truncated in the response.
`filters`	query	string	No	`null`	JSON-encoded array. Select measured answers with objects containing dimension and values. Use labels from list_dimension_options; inspect returned warnings for filters that were not applied.

Request example

Set IQRUSH_API_BASE and IQRUSH_ACCESS_TOKEN through secure configuration. Replace project/run IDs and sample selections with values returned by your account. JSON objects and arrays are encoded as query strings.

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer ${IQRUSH_ACCESS_TOKEN}" \
  --header "Accept: application/json" \
  --data-urlencode metric_family=citation \
  --data-urlencode metric=share \
  --data-urlencode aggregation_level=domain \
  --data-urlencode 'domains=["colorescience.com"]' \
  "${IQRUSH_API_BASE%/}/projects/${IQRUSH_PROJECT_ID}/timeseries/metric"

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. Use explicit run_ids for repeatable reports. The MCP tool has no filters argument in this edition. A single run cannot establish a trend.

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.

Selected response fields from IQRush Dev. Lists are shortened and project/run IDs are placeholders; this is not the full 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. MCP equivalent: get_metric_timeseries. Use the parameters and defaults on this page for HTTP.

If the result is unavailable

Check HTTP status and the response’s error field before using data. A successful empty response does not establish a zero value. Preserve not_available, not_available_reason, unavailable_reason, and linked where returned. Errors and recovery shows observed examples.

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 — HTTP

Parameters

Request example

Read the response

Fields to use

If the result is unavailable

​Parameters

​Request example

​Read the response

​Fields to use

​If the result is unavailable

Parameters

Request example

Read the response

Fields to use

If the result is unavailable