---
title: "List Signals"
method: GET
path: "/{brand_id}/signals"
tags: ["signals"]
---

# List Signals

`GET /{brand_id}/signals`

List detected signals for a brand — statistically-tested movements (level changes and trends) in AI-visibility metrics, produced by the nightly detection sweep.

## Population

By default only user-facing signals are returned: the confidence tiers `high`, `confident`, `worth_a_look`, and `provisional`. Pass an explicit `tier` to select a single tier, including the noise-floor tiers. An ongoing signal is re-detected daily under the same `fingerprint`; a multi-day date range returns only the latest detection per signal identity, so you never see day-by-day duplicates of the same issue.

## Tracking one issue over time

A signal's `fingerprint` is its durable identity: it survives nightly re-detections *and* direction flips of the same underlying issue. To follow an issue after remediation, filter by `fingerprint` with a wide `anchor_from` — a later detection in the opposite `direction` on the same fingerprint is the recovery (or regression) of the original movement. Combine with `direction` to fetch each side separately.

## Sorting

`sort=score_desc` (default) orders by engine priority, `delta_desc` by largest absolute change, `detected_desc` by newest detection date.

## Path parameters

- `brand_id` integer, required

## Query parameters

- `scope` 'account' | 'account_platform' | 'topic' | 'topic_platform', nullable — Slice granularity the signal was detected on: `account` (whole brand), `account_platform` (brand on one AI platform), `topic`, or `topic_platform`.
- `platform` string, nullable — AI platform the signal was detected on (e.g. `OpenAI`). Multi-platform signals carry the `(multi)` sentinel; the response `slice.platforms` lists the real platforms.
- `metric` string, nullable — Metric the signal fired on. Known values: `presence_rate`, `position_top_rate`, `cited_domain_rate` (new metrics may be added).
- `alert_type` 'level_change' | 'trend', nullable — Detection kind: `level_change` (step shift) or `trend` (sustained drift).
- `direction` 'up' | 'down' | 'none', nullable — Direction of the movement: `up`, `down`, or `none`.
- `tier` 'high' | 'confident' | 'worth_a_look' | 'provisional' | 'low_confidence' | 'underpowered' | 'untested', nullable — Confidence tier. When omitted, only the default user-facing tiers are returned (`high`, `confident`, `worth_a_look`, `provisional`); pass an explicit tier to see a single tier, including the noise-floor tiers (`low_confidence`, `underpowered`, `untested`).
- `subject_kind` 'brand' | 'competitor', nullable — Whose movement the signal describes: your `brand` or a `competitor`.
- `anchor_from` string, date, nullable — Earliest `detected_for_date` to include (inclusive, YYYY-MM-DD).
- `anchor_to` string, date, nullable — Latest `detected_for_date` to include (inclusive, YYYY-MM-DD).
- `fingerprint` string, nullable — Only signals with this stable identity (`fingerprint`). A fingerprint survives nightly re-detections and direction flips of the same underlying issue, so filtering on one — with a wide `anchor_from` — tracks how that issue evolved after remediation. Combine with `direction` to separate the original movement from its recovery.
- `mover_url` string, nullable — Case-insensitive substring matched against the URLs in the signal's `url_movers` evidence (per-URL citation movers, emitted for `cited_domain_rate` signals). Only signals with at least one matching mover URL are returned; signals without URL movers never match.
- `sort` 'score_desc' | 'delta_desc' | 'detected_desc' — Sort order: `score_desc` (engine priority, default), `delta_desc` (largest absolute change first), or `detected_desc` (newest first).
- `limit` integer — Maximum number of signals to return.
- `offset` integer — Number of signals to skip (pagination).

## Response `200`

Successful Response

- CollectionResponseAPISignal
  - `total` integer, required
  - `offset` integer
  - `limit` integer, nullable
  - `items` APISignal[], required
    - `id` integer, required — Signal ID. Stable within one detection; use for `getSignal`.
    - `detected_for_date` string, date, required — Anchor date the nightly detection ran for (YYYY-MM-DD).
    - `fingerprint` string, required — Stable identity of the underlying issue across nightly re-detections (hash of the slice + metric). An ongoing signal is re-raised daily under the same fingerprint; reactions are keyed on it.
    - `subject_kind` 'brand' | 'competitor', required — Whose movement the signal describes: your `brand` or a `competitor`.
    - `alert_type` 'level_change' | 'trend', required — Detection kind: `level_change` (step shift) or `trend` (sustained drift).
    - `scope` 'account' | 'account_platform' | 'topic' | 'topic_platform', required — Slice granularity: `account`, `account_platform`, `topic`, or `topic_platform`.
    - `metric` string, required — Metric the signal fired on (e.g. `presence_rate`, `position_top_rate`, `cited_domain_rate`).
    - `platform` string, required — AI platform the signal was detected on. `(multi)` means the slice spans several platforms — see `slice.platforms` for the real list.
    - `direction` 'up' | 'down' | 'none', required — Direction of the movement: `up`, `down`, `none`.
    - `tier` 'high' | 'confident' | 'worth_a_look' | 'provisional' | 'low_confidence' | 'underpowered' | 'untested', required — Confidence tier, best first: `high`, `confident`, `worth_a_look`, `provisional`, then noise-floor tiers `low_confidence`, `underpowered`, `untested` (hidden by default).
    - `current_value` number, required — Metric value over the current window (0-1 rate).
    - `baseline_value` number, required — Metric value over the baseline window (0-1 rate).
    - `delta_absolute` number, required — `current_value - baseline_value` (positive = up).
    - `score` number, nullable — Engine priority score used for the default sort; null for legacy rows.
    - `narrative_what` string, required — One-line headline of what changed.
    - `narrative` APISignalNarrative — Engine-generated narrative for a signal.
      - `what_happened` string, nullable — Plain-language description of the detected change.
      - `why_it_matters` string, nullable — Why the change is significant for the brand.
      - `what_to_do` string, nullable — Suggested next step or investigation.
    - `slice` APISignalSlice, required — The data slice a signal was detected on.
      - `platforms` string[] — AI platforms the slice covers. Empty means all platforms.
      - `topic_labels` string[] — Topic labels the slice covers. Empty means all topics.
      - `geo_country` string, nullable — Country the slice is restricted to, when geo-scoped.
    - `window_current_start` string, date, nullable — Start of the current comparison window.
    - `window_current_end` string, date, nullable — End of the current comparison window.
    - `baseline_definition` string, nullable — Human-readable definition of the baseline window.
    - `url_movers` APISignalUrlMover[] — Per-URL citation movers behind the signal: the brand/competitor URLs whose distinct-response citation counts moved most between the baseline and current windows. Emitted for `cited_domain_rate` signals; empty for other metrics and older signals. Filterable via `mover_url`.
      - `normalized_url` string, required — Normalized cited URL (scheme and tracking params stripped).
      - `owner` 'brand' | 'competitor', required — Whose domain the URL belongs to: `brand` or `competitor`.
      - `competitor_id` integer, nullable — Competitor ID for `competitor`-owned URLs.
      - `competitor_name` string, nullable — Competitor name for `competitor`-owned URLs.
      - `current_responses` integer, required — Distinct responses citing the URL in the current window.
      - `baseline_responses` integer, required — Distinct responses citing the URL in the baseline window.
      - `current_prompts` integer, required — Distinct prompts whose responses cite the URL in the current window.
      - `baseline_prompts` integer, required — Distinct prompts whose responses cite the URL in the baseline window.
      - `contribution` number, nullable — Exact share of the signal's metric delta attributed to this URL. Brand-owned URLs only; null on competitor entries and older signals.
    - `created_at` string, date-time, required — When the signal row was created (UTC).
  - `metadata` TimeSeriesMetadata
    - `aggregation_granularity` 'daily' | 'weekly' | 'monthly', required
    - `period_count` integer, required — The number of periods in the time series
    - `start_date` string, date-time, required — The start date of the time series
    - `end_date` string, date-time, required — The end date of the time series
    - `top_domains` TopDomainsMetadata — Metadata about top domains, used by sources/domains endpoints.
      - `domains` TopDomainSummary[], required — Top domains by observation count (always domain-level aggregated)
        - `domain` string, required
        - `domain_owner` string, required
        - `observation_count` integer, required
      - `grand_total` integer, required — Total observation count across all domains (for calculating 'Other')
      - `owner_totals` object, required — Observation counts by owner type (brand, competitor, other)
      - `owner_time_series` OwnerTimeSeriesPoint[], nullable — Time series data by owner type for trend visualization
        - `time_bucket` string, required — Date string for the time bucket (YYYY-MM-DD)
        - `brand` integer, required — Observation count for brand-owned domains
        - `competitor` integer, required — Observation count for competitor-owned domains
        - `other` integer, required — Observation count for third-party domains
      - `segment_totals` SegmentTotal[] — Server-side observation counts per citation segment (covers all domains, not just top-N)
        - `name` string, required
        - `observation_count` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/scrunchai/apis/scrunch-data-api.md) · [All operations](https://skmtc.net/scrunchai/apis/scrunch-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scrunchai/scrunch-data-api/revisions/c4fe20c603a3/schema)