The feed
List and fetch scored news and filings.
The feed is the core of Forecite: a continuously updated stream of news and filings, each scored by the Verdict Engine.
List feed items
GET /v1/feeds returns a paginated, reverse-chronological list of scored items.
Filtering
Narrow the feed with query parameters — combine as many as you need:
| Parameter | Type | Description |
|---|---|---|
since / until | ISO 8601 | Bound results by published_at. |
symbol | string | Short ticker, e.g. TSLA. |
exchange | string | e.g. NASDAQ, NYSE. |
aggregator | string | Source, e.g. globenewswire. |
actionability | true / false | Only actionable (or non-actionable) items. |
sentiment_min / sentiment_max | integer 0–10 | Bound the sentiment score. |
corp_activity | string | Tag filter — comma-separated values. |
market | string | Tag filter — comma-separated values. |
market_country | string | Tag filter by country. Accepts any ISO 3166-1 alpha-2 code (e.g. US,AE). |
economic_category | string | Tag filter — comma-separated values. |
limit | integer | Page size (capped by your plan). |
cursor | string | Opaque pagination cursor. |
# Actionable NVDA items from the last hour, most bullish first
curl "https://api.forecite.dev/v1/feeds?symbol=NVDA&actionability=true&sentiment_min=7" \
-H "Authorization: Bearer fc_live_your_key_here"Tag filters
There is one query parameter per tag dimension: corp_activity, market,
market_country, and economic_category. Pass a comma-separated list of values
for a dimension to match any of them (OR); values across different
dimensions must all match (AND). Call GET /v1/tags to
discover the valid values (and their display labels) for each dimension.
market_country is special: it accepts any ISO 3166-1 alpha-2 country code
(e.g. US, GB, AE), not only the codes GET /v1/tags lists. That endpoint
returns just the countries that currently have feeds; passing a valid code with
no data yet simply returns no rows.
# US-market earnings or M&A items (country=US AND activity in {earnings, ma})
curl "https://api.forecite.dev/v1/feeds?market_country=US&corp_activity=earnings,ma" \
-H "Authorization: Bearer fc_live_your_key_here"The same tag filters work on the realtime WebSocket stream via the tags
subscription field — see Realtime feeds.
Pagination
Responses include next_cursor. Pass it back as cursor to fetch the next
page; a null cursor means you've reached the end.
let cursor: string | null = null
do {
const url = new URL("https://api.forecite.dev/v1/feeds")
url.searchParams.set("limit", "100")
if (cursor) url.searchParams.set("cursor", cursor)
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.FORECITE_API_KEY}` },
})
const page = await res.json()
handle(page.data)
cursor = page.next_cursor
} while (cursor)Fetch one item
GET /v1/feeds/{id} returns a single item with full per-symbol analysis —
useful when you've seen an id on the WebSocket stream and want the detail.
curl https://api.forecite.dev/v1/feeds/0b3f2c1e-... \
-H "Authorization: Bearer fc_live_your_key_here"The scoring block
Every feed item carries a scoring object from the Verdict Engine:
| Field | Description |
|---|---|
actionability | Whether the item is likely to move price. |
actionability_comment | One-line rationale. |
sentiment_score | Directional score, 0 (most bearish) – 10 (most bullish). |
sentiment_comment | One-line rationale. |
locked | true on the Free plan — scores withheld; see below. |
message | Upgrade prompt, present when locked is true. |
Free plan
The REST history API (/v1/feeds) requires a paid plan. Free users get the
realtime feeds channel (50 items/day) with
Verdict scores locked: scoring.locked is true, the score fields are
null, and scoring.message holds the upgrade prompt. Upgrade to unlock the
actionability and sentiment scores.
See the Verdict Engine for how these are produced, and How to use to run it on your own artifacts.