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.2",
  "server_time":    "2026-07-21T12:25:21.588Z",
  "count":          3,
  "next_since":     "2026-06-16T18:07:38.445456+00:00",
  "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

Returns a single signal with full enrichment: live price data, earnings proximity, dilution risk, filing speed, and insider track records. Makes external API calls — use only for signals that pass your first-pass filter.

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

Response

{
  "schema_version": "1.2",
  "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
      "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"} for unknown IDs.

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.2",
  "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"
    }
  ],
  "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, and detected_at — the fields below that are type-specific. 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

The list endpoint uses a since cursor. Results are ordered by detected_at ASC with id as a stable tiebreaker. On each response, save next_since and pass it as since on the next poll. No results means you are caught up.

// Poll loop (pseudocode)
let since = null

while (true) {
  const url = since
    ? `/api/v1/signals?since=${since}&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) {
    await sleep(60_000) // caught up — wait a minute
  } else {
    since = body.next_since
    // 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

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/.