Signals

Signals are Creative Foresight’s premium alerts: when a series starts moving in a way worth knowing about — accelerating, breaking from its trend, or hitting unusual territory — an interval opens, and it closes when the move ends. Use GET /v1/signals/active for currently open intervals and GET /v1/signals for interval history.

Active signals request


curl "https://api.creativeforesight.io/v1/signals/active?indicator=UNRATE&region=US&strength=strong" \
  -H "Authorization: Bearer $CF_API_KEY"

History request


curl "https://api.creativeforesight.io/v1/signals?indicator=UNRATE&region=US&from=2026-01-01&limit=25" \
  -H "Authorization: Bearer $CF_API_KEY"

Query parameters

Parameter	Type	Endpoint	Description
`indicator`	string	Both	Indicator code filter. May be repeated or comma-separated, such as `indicator=UNRATE,PAYEMS&indicator=cf:labor_composite`.
`region`	string	Both	Region code. Counties use 5-digit FIPS codes.
`type`	`acceleration`, `extreme`, or `trend_break`	Both	Signal type filter.
`strength`	`weak`, `neutral`, or `strong`	Both	Minimum signal strength. Defaults to `neutral`, so weak signals are hidden unless `strength=weak` is requested.
`limit`	integer	Both	Page size. Defaults to 100 for HTTP routes. Active signals are capped to the current open intervals; history uses cursor pagination.
`active`	boolean	`GET /v1/signals`	`true` returns open intervals, `false` returns closed intervals, and omitted returns both.
`from`	date	`GET /v1/signals`	Inclusive lower bound for intervals overlapping this date.
`to`	date	`GET /v1/signals`	Inclusive upper bound for intervals starting on or before this date.
`cursor`	string	`GET /v1/signals`	Cursor from `meta.next_cursor` for the next history page. Ignored by the active endpoint.

Signal object

Field	Type	Description
`id`	string	Stable signal interval identifier.
`indicator`	object	Indicator code, name, category, unit, frequency, and source metadata.
`region`	object	Region code and name.
`type`	string	What kind of move: `acceleration`, `extreme`, or `trend_break`.
`strength`	string	How pronounced the move is: `weak`, `neutral`, or `strong`.
`direction`	string or null	Which way the series is moving, such as `up` or `down`, when applicable.
`valid_from`	date-time	Start of the signal interval.
`valid_to`	date-time or null	End of the interval. Active intervals have `null`.
`detected_at`	date-time	First detection timestamp.
`last_seen_at`	date-time	Latest materialization timestamp for the interval.
`evidence`	object	Opaque supporting detail. Its shape is not part of the API contract and may change — use `text` and `vocabulary` for display.
`vocabulary`	object	Shared chip vocabulary: `glyph`, polarity-aware `label`, and `tone`. `tone` is `positive`, `negative`, or `neutral`.
`text`	string or null	Server-rendered, shareable plain-spoken sentence describing the signal. Non-null for every active indicator (display-metadata coverage is 100% and monitored); typed nullable for defense-in-depth.

Response


{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "indicator": {
        "code": "UNRATE",
        "name": "Unemployment Rate",
        "category": "labor",
        "unit": "percent",
        "frequency": "monthly",
        "source": {
          "slug": "fred",
          "name": "FRED"
        }
      },
      "region": {
        "code": "US",
        "name": "United States"
      },
      "type": "acceleration",
      "strength": "strong",
      "direction": "up",
      "valid_from": "2026-06-01T00:00:00Z",
      "valid_to": null,
      "detected_at": "2026-06-15T00:00:00Z",
      "last_seen_at": "2026-07-10T00:00:00Z",
      "evidence": {
        "…": "…"
      },
      "vocabulary": {
        "glyph": "trending-up",
        "label": "Worsening faster",
        "tone": "negative"
      },
      "text": "The unemployment rate in the United States is mounting – it's been rising faster than its recent trend since June 2026."
    }
  ],
  "meta": {
    "count": 1,
    "limit": 25,
    "filters": {
      "indicator": ["UNRATE"],
      "region": "US",
      "strength": "neutral",
      "active": true
    },
    "next_cursor": "eyJsYXN0U2VlbkF0IjoiMjAyNi0wNy0xMFQwMDowMDowMFoiLCJpZCI6InNpZ18xIn0"
  }
}

meta.next_cursor appears only on GET /v1/signals when another history page is available. Pass it back as cursor with the same filters to continue paging.

Vocabulary and intervals

The signal vocabulary is server-rendered for UI and agent surfaces. glyph is direction-aware, including trending-down for down-accelerations. label is polarity-aware, so the same kind of move can render as Improving faster or Slowing depending on whether higher or lower values are better. tone is derived from direction and indicator polarity — the example above shows a rising unemployment rate (a lower-is-better indicator), so the up-move renders as Worsening faster with negative tone.

A direction flip closes the open interval and starts a new current run. When text says since <date>, that date is the start of the current interval, not a stale first-ever detection date.

Access

Signals require a premium API key or x402 payment. Restricted API keys must include premium access through creative-foresight.

Errors

Status	Code	Meaning
`400`	`INVALID_PARAMETER`	Required or optional query parameters are invalid.
`401`	`INVALID_API_KEY`	The request did not include a valid API key.
`403`	`CATEGORY_NOT_ALLOWED`	The key does not include premium access for signals.
`429`	`RATE_LIMIT_EXCEEDED`	The API key exceeded its one-minute request limit.
`500`	`INTERNAL_ERROR`	Signal data could not be loaded.