Signals API: Detected changes in AI visibility

Overview

The Signals API exposes Scrunch’s nightly detection sweep as a queryable feed. Each signal is a statistically-tested movement — a level change or trend — in one of your brand’s AI visibility metrics on a specific slice of your data (a platform, topic, or the account as a whole). Use it to feed alerts into your own tools, drive weekly briefs, or automate follow-up on the same “what changed” events surfaced in the Scrunch dashboard.

What the Signals API includes

Detected level changes and trends on core metrics (presence_rate, position_top_rate, cited_domain_rate)
A confidence tier for each signal (high, confident, worth_a_look, provisional), with noise-floor tiers available on request
Human-readable narrative: what happened, why it matters, and what to do
A stable fingerprint for each underlying issue — the same signal keeps its fingerprint across nightly re-detections, so reactions and downstream state survive
Reactions (useful, not_useful, dismissed, actioned) with optional free-text reasons, listable brand-wide for team-level reporting
Anchor dates (distinct detection days) for building date pickers and polling loops

Signals are dedup-to-latest per identity: over a multi-day range you see one row per underlying issue, not one row per re-detection.

When to use the Signals API

Use the Signals API when you need to:

Post “what changed this week” summaries to Slack, email, or a stakeholder digest
Route detected drops on a specific platform, topic, or metric into an incident tracker
Export the team’s reactions on signals for reporting or feedback loops
Build a custom alerting dashboard that mirrors the Scrunch Signals feed

For ad-hoc “how is metric X trending” questions, use the Query API — Signals only surfaces movements that pass detection thresholds.

Endpoints

Method	Path	Purpose
GET	`/{brand_id}/signals`	List detected signals with filters.
GET	`/{brand_id}/signals/{signal_id}`	Get one signal with its full narrative.
GET	`/{brand_id}/signals/anchors`	List recent detection dates that produced signals.
GET	`/{brand_id}/signals/reactions`	List reactions across the brand’s signals.
PUT	`/{brand_id}/signals/{signal_id}/reaction`	Set (or replace) the caller’s reaction on a signal.
DELETE	`/{brand_id}/signals/{signal_id}/reaction`	Clear the caller’s reaction.

All endpoints require a bearer token with the query scope. Reaction writes additionally require a user token (JWT) — API keys have no user identity to attribute a reaction to and receive 403. See Authentication.

Filters

The list endpoint accepts:

Filter	Description
`scope`	Slice granularity: `account`, `account_platform`, `topic`, or `topic_platform`.
`platform`	AI platform (e.g. `OpenAI`). Multi-platform signals carry the `(multi)` sentinel; the response `slice.platforms` lists the real platforms.
`metric`	Metric the signal fired on (`presence_rate`, `position_top_rate`, `cited_domain_rate`).
`alert_type`	`level_change` (step shift) or `trend` (sustained drift).
`direction`	`up`, `down`, or `none`.
`subject_kind`	`brand` or `competitor`.
`tier`	Restrict to a single confidence tier. Omitting it returns the default user-facing tiers (`high`, `confident`, `worth_a_look`, `provisional`); pass an explicit tier to include noise-floor tiers (`low_confidence`, `underpowered`, `untested`).
`anchor_from` / `anchor_to`	Inclusive `detected_for_date` bounds (`YYYY-MM-DD`).
`fingerprint`	Exact match on a signal’s stable identity. 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 fetch the original movement and its recovery separately. 1–128 characters.
`mover_url`	Case-insensitive substring matched against the URLs in each signal’s `url_movers` (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. `%` and `_` are matched literally. 1–2048 characters.
`sort`	`score_desc` (default — engine priority), `delta_desc` (largest absolute change), or `detected_desc` (newest detection).
`limit` / `offset`	Page size (default `50`, max `200`) and offset.

The reactions list endpoint supports fingerprint (all reactions on one signal identity) and reaction (all reactions of a given value).

Example: list recent high-confidence signals

curl -X GET \
  "https://api.scrunchai.com/v1/1234/signals?tier=high&sort=detected_desc&limit=20" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"

Response:

{
  "total": 4,
  "offset": 0,
  "limit": 20,
  "items": [
    {
      "id": 90211,
      "detected_for_date": "2026-07-14",
      "fingerprint": "b1e0c7a4f9e5...",
      "subject_kind": "brand",
      "alert_type": "level_change",
      "scope": "account_platform",
      "metric": "presence_rate",
      "platform": "OpenAI",
      "direction": "down",
      "tier": "high",
      "current_value": 0.31,
      "baseline_value": 0.47,
      "delta_absolute": -0.16,
      "score": 0.82,
      "narrative_what": "Brand presence on OpenAI dropped 16 pts week-over-week.",
      "narrative": {
        "what_happened": "Presence on OpenAI fell from 47% to 31% over the last 7 days.",
        "why_it_matters": "OpenAI drives the largest share of your tracked AI traffic.",
        "what_to_do": "Investigate top prompts where the brand disappeared and check citation coverage."
      },
      "slice": {
        "platforms": ["OpenAI"],
        "topic_labels": [],
        "geo_country": null
      },
      "window_current_start": "2026-07-08",
      "window_current_end": "2026-07-14",
      "baseline_definition": "Previous 28 days",
      "url_movers": [],
      "created_at": "2026-07-15T02:14:00Z"
    }
  ]
}

Example: get one signal’s full narrative

curl -X GET \
  "https://api.scrunchai.com/v1/1234/signals/90211" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"

getSignal returns 404 for IDs that exist but aren’t user-facing (non-fired detections or cluster-child rows) — the same population rule as the list endpoint.

Example: react to a signal

Reactions are keyed on the signal’s stable fingerprint, so a thumbs-up survives the nightly re-detection of the same underlying issue. This call requires a user token (JWT).

curl -X PUT \
  "https://api.scrunchai.com/v1/1234/signals/90211/reaction" \
  -H "Authorization: Bearer $SCRUNCH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "reaction": "actioned", "reason": "Filed ticket ENG-4421." }'

{
  "user_id": 55,
  "insight_id": 90211,
  "fingerprint": "b1e0c7a4f9e5...",
  "reaction": "actioned",
  "reason": "Filed ticket ENG-4421.",
  "surface": "api",
  "created_at": "2026-07-15T09:02:11Z",
  "updated_at": "2026-07-15T09:02:11Z"
}

Clear a reaction with DELETE /v1/{brand_id}/signals/{signal_id}/reaction.

Example: list team reactions

The reactions list is brand-wide — it returns every user’s reactions, not just the caller’s — so an integration can export the team’s aggregate feedback.

curl -X GET \
  "https://api.scrunchai.com/v1/1234/signals/reactions?reaction=useful&limit=100" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"

Filter by fingerprint to pull every reaction on one signal identity across re-detections.

Example: poll for new detection dates

curl -X GET \
  "https://api.scrunchai.com/v1/1234/signals/anchors?limit=14" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"

{
  "dates": ["2026-07-14", "2026-07-13", "2026-07-12"]
}

Every returned date has at least one user-facing signal. Use it to drive a date picker or as a cheap check before pulling the full list.

URL movers on citation signals

For cited_domain_rate signals, each response includes a url_movers array — the per-URL citation movers behind the movement. Each mover carries:

Field	Description
`normalized_url`	Cited URL with scheme and tracking params stripped.
`owner`	`brand` (your site) or `competitor`.
`competitor_id` / `competitor_name`	Set on `competitor`-owned URLs.
`current_responses` / `baseline_responses`	Distinct AI responses citing the URL in the current and baseline windows.
`current_prompts` / `baseline_prompts`	Distinct prompts behind those responses.
`contribution`	Exact share of the signal’s metric delta attributed to the URL. Brand-owned URLs only; `null` on competitor entries and on older signals.

url_movers is empty for non-citation metrics and for signals detected before movers were recorded.

Filter signals by mover URL

Use mover_url to narrow the feed to signals whose citation movers touch a specific page or domain fragment. The match is a case-insensitive substring against each mover’s normalized_url.

curl -X GET \
  "https://api.scrunchai.com/v1/1234/signals?metric=cited_domain_rate&mover_url=/pricing&limit=20" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"

Example mover on a returned signal:

{
  "normalized_url": "example.com/pricing",
  "owner": "brand",
  "competitor_id": null,
  "competitor_name": null,
  "current_responses": 42,
  "baseline_responses": 71,
  "current_prompts": 28,
  "baseline_prompts": 49,
  "contribution": -0.08
}

Signals without any URL movers never match mover_url, so combine it with metric=cited_domain_rate when you want a citation-focused feed. % and _ in the input are matched literally.

Signal identity and dedupe

Every signal carries a fingerprint — a hash over its slice and metric — that stays stable across the nightly re-detection of the same underlying issue. Two implications:

List responses dedupe to the latest detection. Over a multi-day anchor_from/anchor_to window you see one row per fingerprint, not one per day.
Reactions follow the fingerprint, not the row ID. A useful set today still applies to tomorrow’s re-detection of the same signal.

Persist the fingerprint (not the numeric id) if you need to correlate signals across runs in your own system.

Track one issue over time

Use the fingerprint filter with a wide anchor_from to follow a single issue through remediation. A later detection with the opposite direction on the same fingerprint is the recovery (or regression) of the original movement. Fetch the original drop:

curl -X GET \
  "https://api.scrunchai.com/v1/1234/signals?fingerprint=b1e0c7a4f9e5...&direction=down&anchor_from=2026-04-01&sort=detected_desc" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"

Then check whether the same fingerprint has since flipped back up:

curl -X GET \
  "https://api.scrunchai.com/v1/1234/signals?fingerprint=b1e0c7a4f9e5...&direction=up&anchor_from=2026-04-01&sort=detected_desc" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"

Signal detections are retained for 180 days, which covers a 90–120 day remediation tracking window.

Best practices

Poll /signals/anchors first to check whether a new detection day exists before pulling the full list.
Sort by detected_desc for “what’s new” digests, score_desc for “what matters most”, and delta_desc when ranking by raw movement.
Store the fingerprint alongside your internal record so reactions and follow-up state survive re-detections.
Use the reactions list to close the loop on “which alerts drove action” — filter by reaction=actioned for a running list of resolved signals.
For automated triage from an AI assistant, the same feed is available through the Scrunch MCP server via the list_signals and get_signal tools.

​Overview

​What the Signals API includes

​When to use the Signals API

​Endpoints

​Filters

​Example: list recent high-confidence signals

​Example: get one signal’s full narrative

​Example: react to a signal

​Example: list team reactions

​Example: poll for new detection dates

​URL movers on citation signals

​Filter signals by mover URL

​Signal identity and dedupe

​Track one issue over time

​Best practices