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`).
`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",
      "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.

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.

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

​Signal identity and dedupe

​Best practices