API Reference

StockNews Search

Fetch real-time, AI-analyzed financial news signals for tickers, agents, dashboards, and research bots.

GEThttps://stocknews.ai/api/news

Free

10 requests/day sample

1-hour delayed. Learning and testing.

Premium

1,000 requests/day

Real-time. Bots, dashboards, alerts.

Pro

5,000 requests/day

Real-time. News Agent and deeper workflows.

Enterprise

Custom

Custom. Teams, licensing, historical access.

Authorizations

Bearer API key

Use one active API key per account. New integrations should use the Authorization header.

Authorizationstringheaderrequired

Bearer authentication header for your account API key.

Bearer sn_live_your_api_key

Query

Request parameters

Use these query parameters to narrow the news feed by ticker, signal strength, source, event type, or pagination.

symbolstringquery

Ticker symbol filter. Comma-separated symbols are supported. Use SPY for general market / S&P 500 market-level news.

AAPL or AAPL,NVDA,MSFT or SPY

limitintegerquery

Maximum number of signals to return. Oversized requests are capped by your plan.

Default: 10

10

cursorIdstringquery

Cursor id returned by the previous page.

665f...

sentimentRatingenum[]query

Filter by AI sentiment label.

verybullish,bullish

verybullishverybearishbullishbearishneutral

stockImpactRatingenum[]query

Filter by expected stock-impact horizon.

shortTerm,longTerm

shortTermnoImpactlongTerm

typeenum[]query

Filter by normalized news/event type.

Earnings,Analyst Rating

Corporate DevelopmentsM&AIndustry NewsResearch AnalysisStock PicksEarningsAnalyst RatingMarket RecapInsidersEconomicOthersLegal

sourcestring[]query

Filter by source. Press Release expands to known press release providers.

Reuters,CNBC,Press Release

ReutersCNBCBenzingaTechCrunchNew York PostBusiness InsiderInvestopediaPress ReleaseBusiness WirePRNewswireGlobeNewsWireAccesswireNewsfile

eventNamestringquery

Use all, or an exact event name stored on the signal. Exact names are case-sensitive.

all or Earnings

General market news

Filter market-level signals

Use the regular /api/news endpoint with symbol=SPY when you want broad market news instead of a single-company feed.

GEThttps://stocknews.ai/api/news?symbol=SPY&limit=10

Use this when your bot or agent needs broad US market context, index-level headlines, and stories that can affect more than one ticker.

Market context

Track broad US market headlines without choosing a single company first.

Index-aware feed

Pull S&P 500-style market stories using the familiar SPY symbol.

Broad feed

Omit symbol when you want the latest news across all symbols instead.

Hot signals

Filter for high-signal news

Use the Hot signals feed when you want a compact list of news items that are already more likely to matter.

GEThttps://stocknews.ai/api/news/top?limit=10

This feed is designed for quick scanning, alerting, and agent workflows where you want higher-signal stories before doing deeper symbol-specific research.

What it returns

High-signal stories selected by StockNews.AI.

Accepted parameters

Use limit and cursorId for pagination. Other /api/news filters do not apply here.

When to use it

Use this for a quick feed of stories worth checking before broad market or symbol-specific scans.

Response

Agent-readable signal schema

Responses are structured for agents, scripts, dashboards, and backtests. Some records may omit optional values depending on the source data.

newsIdstring

Stable news id.

eventIdstring

Grouped event id when multiple sources describe the same story.

titlestring

Original or normalized headline.

signalTitlestring

AI-readable signal title.

urlstring

Original article URL.

sourcestring

Primary source name.

sourcesJson[].sourceUrlstring

Traceable source URL for the event.

publishedAtdatetime

When the original story was published.

firstSeenAtdatetime

When StockNews.AI first saw the story.

latestSourceAtdatetime

Latest source timestamp in the event cluster.

createdAtdatetime

When the signal record was created.

symbolstring

Primary ticker linked to the signal.

namestring

Display ticker/name. S&P 500 is normalized to SPY.

sentimentRatingstring

Formatted sentiment label returned by the API.

stockImpactRatingstring

Impact horizon label, such as shortTerm or longTerm.

typestring

Normalized news type, or Others.

eventNamestring

Event label when the story belongs to an event category.

importanceScorenumber

0-100 estimate of how important the story may be.

sentimentScorenumber

Directional sentiment score.

relevanceScorenumber

How relevant the story is to the returned ticker.

sentimentReasoningstring

Why the model assigned the sentiment.

stockImpactReasoningstring

Why the story may matter for the stock.

startPricenumber

Stock price captured near signal detection for your own backtests.

elapsedTimestring

Human-readable time since createdAt.

pathTitlestring

URL-safe title used by StockNews.AI pages.

trimSummarysarray

Clean summary bullet list.

sourceCountnumber

Number of sources in the event cluster.

newsItemsnumber

Resolved number of related records in the event.

relevantSymbolsarray

Connect ChatGPT with MCP

Use MCP when you want ChatGPT or another AI client to call StockNews.AI tools directly instead of writing REST requests yourself. Use No Auth in the client and pass your StockNews.AI API key in the server URL.

MCPNo Auth

MCP Server URI

https://stocknews.ai/mcp?api_key=sn_live_your_api_key

In ChatGPT custom tools, choose No Auth, paste this URL, and replace the API key with your account key. Tool calls are read-only and count against your API quota.

List tools

ChatGPT can discover StockNews.AI tools such as recent news, semantic news search, company profile, quote, and price-change data.

Call tools

Each MCP tool call uses the same StockNews.AI tool catalog available in News Agent.

Quota

MCP calls use the same monthly API usage bucket as REST so billing stays simple.

JSON-RPC initialize example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "ChatGPT",
      "version": "custom-mcp"
    }
  }
}

Errors

HTTP status codes

The API returns normal HTTP status codes with JSON error bodies. Use response headers to read remaining quota and reset time.

401

Missing or invalid API key

Check the Authorization header or replace the key.

403

Plan does not include this access

Upgrade or remove unsupported filters.

429

Monthly quota exceeded

Wait for reset or upgrade the plan.

500

Server error

Retry later and log the request id if available.

Examples

Copyable examples

Use plain HTTP first. These examples are easy to paste into Cursor, Claude, ChatGPT, notebooks, and small scripts.

curl "https://stocknews.ai/api/news?symbol=NVDA&limit=10&sentimentRating=verybullish,bullish" \
  -H "Authorization: Bearer sn_live_your_api_key"

AI prompts

Prompt examples

Many teams will ask AI to write the integration or interpret the JSON. Give the AI the response and one of these prompts.

Watchlist brief

Use this StockNews.AI response to create a watchlist brief for AAPL, NVDA, MSFT, and TSLA.
Return the top 5 signals, explain why each matters, include the source trace, and flag anything with strong price follow-through.

Trading bot research

You are helping me build a research bot, not executing trades.
Rank signals by importanceScore and relevanceScore.
Explain the catalyst, sentiment, related tickers, and what follow-up data I should check before making a decision.

Cursor coding prompt

Build a small script that calls the StockNews.AI REST API every 15 minutes.
Store newsId, eventId, symbol, signalTitle, importanceScore, sentimentScore, source, firstSeenAt, startPrice.
Skip duplicate newsId values and print an alert when importanceScore is above 80.

Backtesting

Price tracking

The API returns startPrice when the source record has a price snapshot, so you can store the signal-time price and run your own backtests.

Signal-time price

Use startPrice as the entry snapshot for your own tracking logic.

Backtest baseline

Store startPrice with newsId, symbol, and firstSeenAt before calculating later returns.

Your own windows

Compare later market prices against startPrice inside your bot, notebook, or database.