API Reference

Base URL

https://www.clustersignal.app/api/v1

Always use the www. subdomain. clustersignal.app issues a 308 redirect that many HTTP clients drop the Authorization header on.

Authentication

All requests require an API key passed as a Bearer token. Keys require an active API subscription ($19/mo) and are generated at /account/api-keys.

Authorization: Bearer cs_live_<key>

Rate Limits

GET /api/v1/signals

Returns a paginated, cross-type list of signals ordered by detected_at ascending. DB-only — safe to poll frequently.

Query Parameters

Response

{
  "schema_version": "1.6",
  "server_time":    "2026-07-21T12:25:21.588Z",
  "count":          3,
  "next_since":     "2026-06-16T18:07:38.445456+00:00",
  "next_cursor":    "MjAyNi0wNi0xNlQxODowNzozOC40NDU0NTYrMDA6MDB8YzFkMi4uLg",
  "signals":        [ /* Signal objects — shape varies by signal_type, see Signal Types */ ]
}

When requesting multiple signal_types, each type is fetched independently up to limit and the results are merged by detected_at before truncating to the page size, so pagination stays chronologically correct across types.

GET /api/v1/signals/:id

Resolves an id of any signal type. An insider_cluster id comes back with full enrichment: live price data, earnings proximity, dilution risk, filing speed, and insider track records. That path makes external API calls — use it only for signals that pass your first-pass filter.

Every other type returns the same object the list endpoint emits, DB-only, with no price_context — there is no additional enrichment to fetch for those types. Added in 1.6: these ids previously returned 404, which is indistinguishable from a deleted signal, so a strategy gate reading a field off this endpoint failed closed on the entire type. Nothing a consumer needs is detail-only — every field below except price_context and the insider-only flags is already on the list payload.

GET /api/v1/signals/6251ee0d-c83b-452c-8531-85c951b769a6

Response

{
  "schema_version": "1.6",
  "server_time":    "2026-07-21T12:25:21.588Z",
  "signal": {
    /* All list Signal fields plus: */
    "flags": {
      "earnings_proximity_days":   null,   // same value as the list endpoint's field, null if unknown
      "days_to_next_earnings":     76,     // same as the list endpoint's field — use this to gate on an earnings blackout
      "next_earnings_date":        "2026-10-27",
      "dilution_risk":             false,  // >3 filings on same day = potential offering signal
      "volume_spike":              false,  // today's volume > 2× 20-day average
      "filing_speed_same_day_pct": 0       // fraction of insiders who filed same day as trade
    },
    "price_context": {
      "company_name":     "AppFolio, Inc.",
      "sector":           "Information Technology",
      "current_price":    155.145,
      "price_change_pct": null,
      "market_cap":       null,
      "week_52_high":     326.04,
      "week_52_low":      142.56,
      "price_chart": {
        "timestamps": [ /* Unix timestamps */ ],
        "closes":     [ /* Close prices  */ ],
        "volumes":    [ /* Daily volumes */ ]
      },
      "price_return": {
        "priceAtCluster": 159.68,
        "return_30d":     null,   // null until enough time has passed
        "return_60d":     null,
        "return_90d":     null
      },
      "win_rate":             null,
      "signal_summary":       "Signal Strength: ...",
      "insider_track_records": [
        {
          "insider_cik":       "2082975",
          "insider_name":      "Rigler Don",
          "officer_title":     null,
          "trade_direction":   "buy",  // this insider's own direction in this cluster — "first_time_buyer" is only ever true for "buy"
          "is_first_time_buyer": true,
          "prior_trades":      []      // prior buys for a "buy" insider, prior sales for a "sell" insider — never mixed
        }
      ]
    }
  }
}

Returns 404 with {"error":"not_found"} only when no signal of any type carries that id. On a non-insider type, flags.dilution_risk, volume_spike and filing_speed_same_day_pct are null — absent, not measured-and-negative. An aligned_signal shares its id with the congressional cluster or contract award it was derived from, so those ids resolve here as congressional_cluster or gov_contract — the same underlying event, reported under its own type.

GET /api/v1/tickers/:symbol/summary

Everything known about one ticker across every signal type, in a single response. DB-only — no external API calls, safe to poll.

GET /api/v1/tickers/PLTR/summary

Response

{
  "schema_version": "1.6",
  "server_time":    "2026-07-21T12:25:21.588Z",
  "ticker":         "PLTR",
  "company_name":   null,
  "sector":         null,
  "insider_clusters":       [ /* insider_cluster signals, up to 100 */ ],
  "congressional_clusters": [ /* congressional_cluster signals, up to 100 */ ],
  "aligned_signals":        [ /* aligned_signal signals, up to 100 */ ],
  "trademark_filings":      [ /* trademark_filing signals, up to 100 */ ],
  "activist_stakes":        [ /* activist_stake signals, up to 100 */ ],
  "fund_positions":         [ /* fund_position signals, up to 100 */ ],
  "gov_contracts": [
    {
      "signal_type":      "gov_contract",
      "id":               "40a0e34d-feb4-43ab-80d3-029512312c3c",
      "ticker":           "PLTR",
      "recipient_name":   "PALANTIR TECHNOLOGIES INC.",
      "awarding_agency":  "Department of Homeland Security",
      "award_amount":     45848616.8,
      "start_date":       "2026-06-26",
      "aligned_with_congressional_trade": false,
      "usaspending_url":  "https://www.usaspending.gov/award/CONT_AWD_...",
      "detected_at":      "2026-07-20T13:04:41.199363+00:00",
      "next_earnings_date":      "2026-11-03",   // added in 1.6 — on every type
      "days_to_next_earnings":   83,
      "earnings_proximity_days": null
    }
  ],
  "fda_catalysts": [ /* fda_catalyst signals, up to 100 */ ]
}

Unknown tickers return 200 with every array empty, not a 404 — there's no canonical ticker list to validate against.

Signal Object

Fields present on every signal (list and detail).

Filing Object

Signal Types

Every object in signals carries signal_type, id, ticker, detected_at, and — since 1.6 — the three earnings fields (next_earnings_date, days_to_next_earnings, earnings_proximity_days), which are facts about the ticker and are derived identically for all eight types. The fields below are the type-specific ones. ticker is null when the underlying filer/recipient/sponsor couldn't be matched to a public company (deliberately conservative — an exact-normalized-name match only, never fuzzy, to avoid misattributing a signal to the wrong ticker).

congressional_cluster

2+ members of Congress trading the same ticker/direction within a 60-day window. Source: House disclosures.

aligned_signal

Cross-source corroboration — two independent signal sources point to the same ticker around the same time. A stronger signal than either source alone.

trademark_filing

New USPTO trademark applications from publicly traded companies — can signal unannounced products/brands.

activist_stake

SEC Schedule 13D/13G beneficial-ownership filings — someone crossing the 5% ownership threshold.

fund_position

Quarter-over-quarter position changes from ~20 tracked notable 13F filers (Berkshire Hathaway, Renaissance Technologies, Citadel, etc.) — new positions, full exits, and adds/trims of 20%+.

gov_contract

New federal prime contract awards ≥ $10M from USAspending.gov, matched to a public recipient where possible.

fda_catalyst

Forward-looking Phase 3 clinical trial readouts for publicly traded biotechs, from clinicaltrials.gov. PDUFA dates are not tracked — there's no official structured source for them.

Errors

All error responses use the same shape:

{ "error": "human-readable description" }

Pagination

Results are ordered by detected_at ASC with id as a stable tiebreaker — together a total order, so every signal has exactly one position. Save next_cursor from each response and pass it back as cursor. An empty response means you are caught up; keep your last cursor and re-send it on the next poll.

Use cursor, not since. since filters on detected_at alone, and that value is not unique: a bulk historical ingest stamps thousands of signals within the same microsecond, and even routine batches produce groups of 100–200. When such a group spans a page boundary, next_since advances past the entire group and its remaining signals become unreachable — and if one group is larger than limit, pagination cannot advance at all. Draining the activist_stake corpus with since at limit=100 reaches 17.7% of it; with cursor it reaches all of it. since is retained so existing integrations keep working, but it cannot be made complete.

// Poll loop (pseudocode)
let cursor = null   // persist this across restarts

while (true) {
  const url = cursor
    ? `/api/v1/signals?cursor=${encodeURIComponent(cursor)}&limit=100`
    : '/api/v1/signals?limit=100'

  const res  = await fetch(url, { headers })
  const body = await res.json()

  for (const signal of body.signals) {
    process(signal)
  }

  if (body.count === 0) {
    // caught up — keep the existing cursor and wait
    await sleep(60_000)
  } else {
    cursor = body.next_cursor
    // more pages may exist — loop immediately
  }
}

Examples

List signals (curl)

curl -s "https://www.clustersignal.app/api/v1/signals?limit=10&direction=buy&min_grade=B" \
  -H "Authorization: Bearer cs_live_<your_key>"

Fetch signal detail (curl)

curl -s "https://www.clustersignal.app/api/v1/signals/<signal_id>" \
  -H "Authorization: Bearer cs_live_<your_key>"

List signals (JavaScript)

const BASE = 'https://www.clustersignal.app/api/v1'
const KEY  = process.env.CLUSTERSIGNAL_API_KEY

async function fetchSignals(since?: string) {
  const url = new URL(`${BASE}/signals`)
  url.searchParams.set('limit', '100')
  if (since) url.searchParams.set('since', since)

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${KEY}` },
  })
  if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`)
  return res.json()
}

async function fetchDetail(id: string) {
  const res = await fetch(`${BASE}/signals/${id}`, {
    headers: { Authorization: `Bearer ${KEY}` },
  })
  if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`)
  return res.json()
}

Filter for high-conviction buys only

GET /api/v1/signals?direction=buy&min_grade=A&limit=50

Filter for short-radar sells

# Fetch sells, then filter is_short_radar === true client-side
GET /api/v1/signals?direction=sell&limit=100

# Or use min_score to tighten the set
GET /api/v1/signals?direction=sell&min_score=50&limit=100

Poll every new signal type at once

GET /api/v1/signals?signal_type=congressional_cluster,aligned_signal,trademark_filing,activist_stake,fund_position,gov_contract,fda_catalyst&limit=100

Earnings blackout gate (any signal type)

// days_to_next_earnings is on every signal from the list endpoint, so the gate
// never needs the detail endpoint and never branches on signal_type.
const BLACKOUT_DAYS = 3

function tradeable(signal) {
  const d = signal.days_to_next_earnings
  if (d === null) return FAIL_OPEN_ON_UNKNOWN   // your policy — see below
  return d > BLACKOUT_DAYS
}

// null means "no upcoming date is known for this ticker", never "the ticker is
// clear". Whether that blocks a trade is your call, but know the cost: the
// calendar source omits some tickers outright (ETFs, most foreign issuers, and
// a tail of ordinary names), so failing closed on null permanently blocks them
// rather than blocking them for a few days. Measured 2026-08-12: 18 of 202
// tickers across the congressional corpus had no date on file at all.

// Do NOT gate on earnings_proximity_days. It is measured from the signal's own
// event date, which on a backfilled type is often a year old — it is null for
// most rows and says nothing about today.

One ticker, one call, every signal type

curl -s "https://www.clustersignal.app/api/v1/tickers/PLTR/summary" \
  -H "Authorization: Bearer cs_live_<your_key>"

Changelog

Additive changes (new optional fields, new optional query params) happen within v1 and bump schema_version. Breaking changes go to /api/v2/.