API Reference

Base URL: https://www.instnews.net

All responses are JSON. Authentication is optional — unauthenticated requests receive free-tier access, no API key required. Send X-API-Key: <key> (Pro and Max; create keys in your account dashboard) or Authorization: Bearer <token> to unlock your paid tier.

Machine-readable spec: OpenAPI 3.1 spec (/openapi.json).

Rate Limits

Tier	Requests per minute	Items per request	History depth
Free	30	50	7 days
Pro	300	200	1 year
Max	1,000	500	5 years

Exceeding the rate limit returns 429.

GET/api/news

Returns news items, newest first, with optional filtering.

Parameter	Type	Default	Description
`limit`	int	tier max	Number of items (Free: 50, Pro: 200, Max: 500). With `from`/`to` set on Pro/Max, up to 5× the tier max (hard cap 2,000)
`source`	string	`all`	Filter by a single source name (see `/api/sources`)
`sources`	string	—	Comma-separated source names (up to 100). An empty value (`sources=`) returns no items
`source_type`	string	`all`	`social` (X/Twitter and Truth Social accounts) or `rss` (every non-social source)
`sentiment`	string	`all`	Filter: `bullish`, `bearish`, `neutral`
`q`	string	—	Keyword search in title and summary
`tickers`	string	—	Comma-separated tickers (up to 100, case-insensitive), matched against each item's `target_asset`. All tiers
`from`	string	—	Start date (ISO 8601). Pro and Max
`to`	string	—	End date (ISO 8601; a bare `YYYY-MM-DD` includes the whole day). Pro and Max
`before`	int	—	Cursor: only items with `id` lower than this (older page). Pass the previous response's `next_before`
`after`	int	—	Cursor: only items with `id` higher than this (newer arrivals since your last poll)
`hide_dup`	bool	—	`1`/`true` drops items flagged as duplicates. Pro and Max (ignored on Free)
`tradable`	bool	—	`1`/`true` returns only items the AI marked tradeable. Max only (ignored on other tiers)

curl -s "https://www.instnews.net/api/news?tickers=NVDA,AMD&limit=10" | jq .

Response envelope: {"count": N, "items": [...], "next_before": <id or null>}.

Response Fields

Field	Free	Pro	Max	Description
`id`	✓	✓	✓	Unique item ID (cursor for `before`/`after`)
`title`	✓	✓	✓	Headline text
`link`	✓	✓	✓	URL to original article
`source`	✓	✓	✓	Feed source name
`published`	✓	✓	✓	Publication time (ISO 8601)
`fetched_at`	✓	✓	✓	Time InstNews ingested the item (ISO 8601)
`summary`	✓	✓	✓	Article excerpt (max 500 chars)
`target_asset`	✓	✓	✓	The one ticker the item is about (AI-assigned), or null
`asset_type`	✓	✓	✓	Asset class of `target_asset` (e.g. `STOCK`)
`sentiment_score`	✗	✓	✓	Score from -1.0 to 1.0
`sentiment_label`	✗	✓	✓	`bullish`, `bearish`, or `neutral`
`duplicate`	✗	✓	✓	1 if duplicate, 0 if original
`confidence`	✗	✗	✓	AI confidence in the ticker call (0–1)
`risk_level`	✗	✗	✓	AI risk assessment
`tradeable`	✗	✗	✓	Whether the AI considers the item actionable
`reasoning`	✗	✗	✓	Short AI rationale for the ticker call
`priced_in`	✗	✗	✓	Pre-news price run-up score (with `priced_in_detail`, `priced_in_checked`)

GET/api/news/stream

Server-Sent Events (text/event-stream) push of items as their AI analysis lands. Every tier can connect; each event's data is shaped with the same per-tier field rules as /api/news.

Parameter	Type	Default	Description
`since_seq`	int or `latest`	`latest`	Resume cursor. A number replays every event after that sequence, then streams live. `latest` (or omitted) starts at the live tail and first sends a `cursor` event carrying the current sequence

Wire format — one frame per event; id is the event sequence:

id: 1234
event: verdict
data: {"seq": 1234, "event_type": "verdict", "emitted_at": "2026-10-18T14:30:05+00:00", "data": {"news_id": 98765, "title": "...", "source": "...", "target_asset": "NVDA", ...}}

: hb 1760797805

Event types: verdict (an item's analysis landed), priced_in (a priced-in score landed later for the same item), cursor (initial marker with {"seq": N} when starting from latest).
Heartbeat: a comment line : hb <unix time> about every 15 seconds while idle.
Lifetime: the server closes each stream after a bounded lifetime (10 minutes by default). Reconnect with since_seq set to the last id you received — nothing is lost.
Capacity: when all stream slots are busy the endpoint returns 503 with Retry-After; fall back to polling /api/news?after= and retry later.

curl -N "https://www.instnews.net/api/news/stream"

GET/api/sources

Returns all active feed sources with item counts.

curl -s "https://www.instnews.net/api/sources" | jq .

GET/api/stats

Returns aggregated statistics: total items, by source, by sentiment, average score.

curl -s "https://www.instnews.net/api/stats" | jq .

GET/api/auth/me

Requires authentication. Returns the current user's profile.

GET/api/auth/tier

Returns the current user's tier, feature flags, and limits. Works for anonymous users.

POST/api/billing/checkout

Requires authentication. Creates a Stripe Checkout session for upgrading.

// Request body
{"tier": "pro"}

// Response
{"url": "https://checkout.stripe.com/c/pay/cs_..."}

Error Responses

Status	Meaning
`400`	Bad request (invalid parameters)
`401`	Authentication required
`403`	Feature not available on your tier
`429`	Rate limit exceeded
`503`	Service unavailable (e.g. Stripe not configured, all stream slots busy)