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

API key header

Use one active API key per account. New REST integrations should send it in the x-api-key header. Browser-style clients can use api_key as a query parameter.

x-api-keystringheaderrequired

Recommended API key header for REST requests. You can also pass api_key as a query parameter for browser-style clients.

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-based pagination. Pass the last item's newsId from the previous response to fetch older signals.

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 broad AI news category, such as Earnings, Analyst Rating, M&A, Economic, Legal, or Industry News.

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 WirePRNewswirePRNewsWireGlobeNewsWireGlobe NewswireAccesswireACCESS NewswireNewsfileNewsfile Corp.

eventNamestringquery

Filter by catalyst/event pipeline label. Use all for any event, or an exact event such as Earnings, M&A, Shares Buyback, Mass Contract, Lawsuit, Layoff, or FDA Approval.

all or Mass Contract

allEarningsM&AShares BuybackMass ContractLawsuitLeadership ChangeActivistShort SellerDividend ChangeStock SplitFDA ApprovalLayoffBankruptcy

Filters

Type vs eventName

Use type for broad news categories. Use eventName when your trading agent is looking for specific catalysts.

type

Broad category filter

Use this to pull general categories such as Earnings, Analyst Rating, M&A, Economic, Legal, Industry News, or Corporate Developments.

/api/news?type=Earnings,Analyst%20Rating

eventName

Catalyst event filter

Use this for the dedicated event pipeline: Earnings, M&A, Shares Buyback, Mass Contract, Lawsuit, Layoff, FDA Approval, Bankruptcy, and related event labels.

/api/news?eventName=Mass%20Contract

Pagination

Cursor-based pagination

Use limit for page size. To fetch older signals, pass the last returned item's newsId as cursorId on the next request.

First page/api/news?symbol=NVDA&limit=10

Store the last item's newsId from data. Results are sorted newest first.

Next page/api/news?symbol=NVDA&limit=10&cursorId=last_newsId

Keep the same filters and replace cursorId with the previous page's last newsId.

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/api/mcp?api_key=sn_live_your_api_key

In ChatGPT, create a custom app, 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.

ChatGPT setup

Go to ChatGPT settings, open Apps, choose Add more, then create a new app with the MCP Server URL and No Auth.

Enabled apps

Manage enabled apps ChatGPT can use in your chats.

Add more

General

Notifications

Personalization

Apps

Schedules

Billing

GitHub

›

stocknewsai DEV

›

⚙

Advanced settings Create app

›

Drafts

Private apps you've created in developer mode.

New App BETA

Name

stocknewsai

Description (optional)

AI-analyzed stock news signals

MCP Server URL

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

Authentication

No Auth ⌄

Custom MCP servers introduce risk.

✓

I understand and want to continue

Review the warning, check the box, then create the app.

Create

List tools

ChatGPT can discover StockNews.AI tools, including standard search/fetch plus 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 x-api-key header, api_key query parameter, 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 "x-api-key: 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.