Insights

GET /v1/insights returns salience-ranked computed facts for one indicator series and includes active signals when available. Facts are deterministic descriptive calculations over observations; they are not LLM-generated text.

Request

curl "https://api.creativeforesight.io/v1/insights?indicator=UNRATE&region=US&window=5y" \
  -H "Authorization: Bearer $CF_API_KEY"

Query parameters

Fact kinds

Every fact includes kind, typed params, humanTemplate, salience, and text. text is a server-rendered, shareable plain-spoken sentence (see Shareable prose); it is non-null for every active indicator — display-metadata coverage is 100% and a daily monitor keeps it there. The field is typed nullable for defense-in-depth (see Shareable prose). Salience is a deterministic score from 0 to 1 based on magnitude, recency, and extremeness.

Response

{
  "facts": [
    {
      "kind": "watermark_high_distance",
      "params": {
        "latestDate": "2024-01-01",
        "latestValue": 160,
        "watermarkDate": "2024-01-01",
        "watermarkValue": 160,
        "distance": 0,
        "percentDistance": 0
      },
      "humanTemplate": "Latest value is {distance} from the series high of {watermarkValue} on {watermarkDate}.",
      "salience": 1,
      "text": "The unemployment rate in the United States hit an all-time high in 2024."
    }
  ],
  "signals": [
    {
      "id": "sig_1",
      "indicator": "UNRATE",
      "region": "US",
      "kind": "acceleration",
      "strength": "strong",
      "direction": "up",
      "salience": 0.9,
      "summary": "Worsening faster – Unemployment Rate (United States)",
      "text": "The unemployment rate in the United States is mounting – it's been rising faster than its recent trend since April 2026.",
      "observed_at": "2026-07-10T00:00:00Z",
      "evidence": {
        "…": "…"
      },
      "vocabulary": {
        "glyph": "trending-up",
        "label": "Worsening faster",
        "tone": "negative"
      }
    }
  ],
  "meta": {
    "indicator": "UNRATE",
    "region": "US",
    "unit": "percent",
    "window": "5y",
    "observation_count": 5
  }
}

Signals

When an active signal is available for the resolved indicator and region, the signals array includes it alongside the computed facts. Signal strength is weak, neutral, or strong; direction is up or down when applicable; vocabulary provides the shared glyph, polarity-aware label, and tone (positive, negative, or neutral).

Shareable prose

Every fact and signal carries a text field: a server-rendered, plain-spoken sentence that reads cleanly on its own — a chart caption, a chat reply, or a social post — with no knowledge of the underlying schema required.

• Deterministic, not LLM-generated. text is rendered at request time from the same computed params by a pure function; identical inputs always produce identical copy.
• Polarity-aware language. Verbs come from indicators.extra.display.polarity: higher-is-better, lower-is-better, or neutral. Missing polarity uses neutral wording.
• Guaranteed for active indicators. Every active indicator carries a curated display noun and unit, so text is non-null across the catalog; a daily coverage monitor alerts on any regression. The field stays typed nullable as a defensive contract — if you want a belt-and-suspenders fallback, humanTemplate + params always reconstruct a value — but in practice text is always present.
• Formatting. Large values are spelled out ($821 million, $1.1 billion); values below a million are written in full with separators ($457,172). Prose uses en-dashes, never em-dashes.

For example, a trend fact renders as “Between 2007 and 2021, Williamson County’s revenue grew 119% – from $374 million to $821 million, about 5.8% a year.”, and an acceleration signal renders as “The unemployment rate in the United States is mounting – it’s been rising faster than its recent trend since April 2026.”

Access

Insights use the same access_tier rule as observations. If the resolved indicator is premium, the request needs an unrestricted key, a key granting creative-foresight, or x402.

Errors