> ## Documentation Index > Fetch the complete documentation index at: https://developers.scrunch.com/llms.txt > Use this file to discover all available pages before exploring further. # List 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. ## OpenAPI ````yaml /api-reference/openapi.json get /{brand_id}/signals openapi: 3.1.0 info: title: Scrunch Data API version: 0.1.0 servers: - url: https://api.scrunchai.com/v1 security: [] paths: /{brand_id}/signals: get: tags: - signals summary: List Signals description: >- 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. operationId: listSignals parameters: - name: brand_id in: path required: true schema: type: integer title: Brand Id - name: scope in: query required: false schema: anyOf: - enum: - account - account_platform - topic - topic_platform type: string - type: 'null' description: >- Slice granularity the signal was detected on: `account` (whole brand), `account_platform` (brand on one AI platform), `topic`, or `topic_platform`. title: Scope description: >- Slice granularity the signal was detected on: `account` (whole brand), `account_platform` (brand on one AI platform), `topic`, or `topic_platform`. - name: platform in: query required: false schema: anyOf: - type: string - type: 'null' description: >- 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. title: Platform description: >- 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. - name: metric in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Metric the signal fired on. Known values: `presence_rate`, `position_top_rate`, `cited_domain_rate` (new metrics may be added). title: Metric description: >- Metric the signal fired on. Known values: `presence_rate`, `position_top_rate`, `cited_domain_rate` (new metrics may be added). - name: alert_type in: query required: false schema: anyOf: - enum: - level_change - trend type: string - type: 'null' description: >- Detection kind: `level_change` (step shift) or `trend` (sustained drift). title: Alert Type description: >- Detection kind: `level_change` (step shift) or `trend` (sustained drift). - name: direction in: query required: false schema: anyOf: - enum: - up - down - none type: string - type: 'null' description: 'Direction of the movement: `up`, `down`, or `none`.' title: Direction description: 'Direction of the movement: `up`, `down`, or `none`.' - name: tier in: query required: false schema: anyOf: - enum: - high - confident - worth_a_look - provisional - low_confidence - underpowered - untested type: string - type: 'null' description: >- 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`). title: Tier description: >- 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`). - name: subject_kind in: query required: false schema: anyOf: - enum: - brand - competitor type: string - type: 'null' description: >- Whose movement the signal describes: your `brand` or a `competitor`. title: Subject Kind description: 'Whose movement the signal describes: your `brand` or a `competitor`.' - name: anchor_from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Earliest `detected_for_date` to include (inclusive, YYYY-MM-DD). title: Anchor From description: Earliest `detected_for_date` to include (inclusive, YYYY-MM-DD). - name: anchor_to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Latest `detected_for_date` to include (inclusive, YYYY-MM-DD). title: Anchor To description: Latest `detected_for_date` to include (inclusive, YYYY-MM-DD). - name: fingerprint in: query required: false schema: anyOf: - type: string minLength: 1 maxLength: 128 - type: 'null' description: >- 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. title: Fingerprint description: >- 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. - name: mover_url in: query required: false schema: anyOf: - type: string minLength: 1 maxLength: 2048 - type: 'null' description: >- 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. title: Mover Url description: >- 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. - name: sort in: query required: false schema: enum: - score_desc - delta_desc - detected_desc type: string description: >- Sort order: `score_desc` (engine priority, default), `delta_desc` (largest absolute change first), or `detected_desc` (newest first). default: score_desc title: Sort description: >- Sort order: `score_desc` (engine priority, default), `delta_desc` (largest absolute change first), or `detected_desc` (newest first). - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 description: Maximum number of signals to return. default: 50 title: Limit description: Maximum number of signals to return. - name: offset in: query required: false schema: type: integer minimum: 0 description: Number of signals to skip (pagination). default: 0 title: Offset description: Number of signals to skip (pagination). responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CollectionResponse_APISignal_' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: - query components: schemas: CollectionResponse_APISignal_: properties: total: type: integer title: Total offset: type: integer title: Offset default: 0 limit: anyOf: - type: integer - type: 'null' title: Limit items: items: $ref: '#/components/schemas/APISignal' type: array title: Items metadata: anyOf: - $ref: '#/components/schemas/TimeSeriesMetadata' - type: 'null' type: object required: - total - items title: CollectionResponse[APISignal] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError APISignal: properties: id: type: integer title: Id description: Signal ID. Stable within one detection; use for `getSignal`. detected_for_date: type: string format: date title: Detected For Date description: Anchor date the nightly detection ran for (YYYY-MM-DD). fingerprint: type: string title: Fingerprint description: >- 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: type: string enum: - brand - competitor title: Subject Kind description: 'Whose movement the signal describes: your `brand` or a `competitor`.' alert_type: type: string enum: - level_change - trend title: Alert Type description: >- Detection kind: `level_change` (step shift) or `trend` (sustained drift). scope: type: string enum: - account - account_platform - topic - topic_platform title: Scope description: >- Slice granularity: `account`, `account_platform`, `topic`, or `topic_platform`. metric: type: string title: Metric description: >- Metric the signal fired on (e.g. `presence_rate`, `position_top_rate`, `cited_domain_rate`). platform: type: string title: Platform description: >- AI platform the signal was detected on. `(multi)` means the slice spans several platforms — see `slice.platforms` for the real list. direction: type: string enum: - up - down - none title: Direction description: 'Direction of the movement: `up`, `down`, `none`.' tier: type: string enum: - high - confident - worth_a_look - provisional - low_confidence - underpowered - untested title: Tier description: >- Confidence tier, best first: `high`, `confident`, `worth_a_look`, `provisional`, then noise-floor tiers `low_confidence`, `underpowered`, `untested` (hidden by default). current_value: type: number title: Current Value description: Metric value over the current window (0-1 rate). baseline_value: type: number title: Baseline Value description: Metric value over the baseline window (0-1 rate). delta_absolute: type: number title: Delta Absolute description: '`current_value - baseline_value` (positive = up).' score: anyOf: - type: number - type: 'null' title: Score description: >- Engine priority score used for the default sort; null for legacy rows. narrative_what: type: string title: Narrative What description: One-line headline of what changed. narrative: anyOf: - $ref: '#/components/schemas/APISignalNarrative' - type: 'null' description: >- Full narrative (what happened / why it matters / what to do), when available. slice: $ref: '#/components/schemas/APISignalSlice' description: The data slice the signal was detected on. window_current_start: anyOf: - type: string format: date - type: 'null' title: Window Current Start description: Start of the current comparison window. window_current_end: anyOf: - type: string format: date - type: 'null' title: Window Current End description: End of the current comparison window. baseline_definition: anyOf: - type: string - type: 'null' title: Baseline Definition description: Human-readable definition of the baseline window. url_movers: items: $ref: '#/components/schemas/APISignalUrlMover' type: array title: Url Movers description: >- 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`. created_at: type: string format: date-time title: Created At description: When the signal row was created (UTC). type: object required: - id - detected_for_date - fingerprint - subject_kind - alert_type - scope - metric - platform - direction - tier - current_value - baseline_value - delta_absolute - narrative_what - slice - created_at title: APISignal description: A detected, statistically-tested movement in an AI-visibility metric. TimeSeriesMetadata: properties: aggregation_granularity: $ref: '#/components/schemas/AggregationGranularity' description: 'The aggregation granularity: daily, weekly, or monthly' period_count: type: integer title: Period Count description: The number of periods in the time series start_date: type: string format: date-time title: Start Date description: The start date of the time series end_date: type: string format: date-time title: End Date description: The end date of the time series top_domains: anyOf: - $ref: '#/components/schemas/TopDomainsMetadata' - type: 'null' description: Top domains metadata (only populated by sources/domains endpoints) type: object required: - aggregation_granularity - period_count - start_date - end_date title: TimeSeriesMetadata ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError APISignalNarrative: properties: what_happened: anyOf: - type: string - type: 'null' title: What Happened description: Plain-language description of the detected change. why_it_matters: anyOf: - type: string - type: 'null' title: Why It Matters description: Why the change is significant for the brand. what_to_do: anyOf: - type: string - type: 'null' title: What To Do description: Suggested next step or investigation. type: object title: APISignalNarrative description: Engine-generated narrative for a signal. APISignalSlice: properties: platforms: items: type: string type: array title: Platforms description: AI platforms the slice covers. Empty means all platforms. topic_labels: items: type: string type: array title: Topic Labels description: Topic labels the slice covers. Empty means all topics. geo_country: anyOf: - type: string - type: 'null' title: Geo Country description: Country the slice is restricted to, when geo-scoped. type: object title: APISignalSlice description: The data slice a signal was detected on. APISignalUrlMover: properties: normalized_url: type: string title: Normalized Url description: Normalized cited URL (scheme and tracking params stripped). owner: type: string enum: - brand - competitor title: Owner description: 'Whose domain the URL belongs to: `brand` or `competitor`.' competitor_id: anyOf: - type: integer - type: 'null' title: Competitor Id description: Competitor ID for `competitor`-owned URLs. competitor_name: anyOf: - type: string - type: 'null' title: Competitor Name description: Competitor name for `competitor`-owned URLs. current_responses: type: integer title: Current Responses description: Distinct responses citing the URL in the current window. baseline_responses: type: integer title: Baseline Responses description: Distinct responses citing the URL in the baseline window. current_prompts: type: integer title: Current Prompts description: Distinct prompts whose responses cite the URL in the current window. baseline_prompts: type: integer title: Baseline Prompts description: >- Distinct prompts whose responses cite the URL in the baseline window. contribution: anyOf: - type: number - type: 'null' title: Contribution description: >- Exact share of the signal's metric delta attributed to this URL. Brand-owned URLs only; null on competitor entries and older signals. type: object required: - normalized_url - owner - current_responses - baseline_responses - current_prompts - baseline_prompts title: APISignalUrlMover description: A per-URL citation mover backing a `cited_domain_rate` signal. AggregationGranularity: type: string enum: - daily - weekly - monthly TopDomainsMetadata: properties: domains: items: $ref: '#/components/schemas/TopDomainSummary' type: array title: Domains description: Top domains by observation count (always domain-level aggregated) grand_total: type: integer title: Grand Total description: Total observation count across all domains (for calculating 'Other') owner_totals: additionalProperties: type: integer type: object title: Owner Totals description: Observation counts by owner type (brand, competitor, other) owner_time_series: anyOf: - items: $ref: '#/components/schemas/OwnerTimeSeriesPoint' type: array - type: 'null' title: Owner Time Series description: Time series data by owner type for trend visualization segment_totals: items: $ref: '#/components/schemas/SegmentTotal' type: array title: Segment Totals description: >- Server-side observation counts per citation segment (covers all domains, not just top-N) type: object required: - domains - grand_total - owner_totals title: TopDomainsMetadata description: Metadata about top domains, used by sources/domains endpoints. TopDomainSummary: properties: domain: type: string title: Domain domain_owner: type: string title: Domain Owner observation_count: type: integer title: Observation Count type: object required: - domain - domain_owner - observation_count title: TopDomainSummary OwnerTimeSeriesPoint: properties: time_bucket: type: string title: Time Bucket description: Date string for the time bucket (YYYY-MM-DD) brand: type: integer title: Brand description: Observation count for brand-owned domains competitor: type: integer title: Competitor description: Observation count for competitor-owned domains other: type: integer title: Other description: Observation count for third-party domains type: object required: - time_bucket - brand - competitor - other title: OwnerTimeSeriesPoint description: A single time bucket with observation counts by owner type. SegmentTotal: properties: name: type: string title: Name observation_count: type: integer title: Observation Count type: object required: - name - observation_count title: SegmentTotal description: Observation count for a citation segment, computed server-side. securitySchemes: HTTPBearer: type: http scheme: bearer ```` ## Related topics - [Scrunch MCP Feature Reference and Example Prompts](/mcp/tools.md) - [List Signal Reactions](/api-reference/signals/list-signal-reactions.md) - [List Signal Anchor Dates](/api-reference/signals/list-signal-anchor-dates.md)