Which Endpoint Should I Use?
Map your use case to the right endpoint — from raw news to trading signals and systematic indices.
Not sure where to start? Find your use case below and go straight to the endpoint that fits.
I want to...
Get the latest news for an asset
Use GET /v1/headlines/feed/live/ticker/{ticker}
Returns the most recent headlines for a ticker, each scored with sentiment and classified by topic. This is the most granular data in the API — individual articles, not aggregated.
Get a directional signal for a ticker
Use GET /v1/signals
Returns a bullish / bearish / neutral decision for one or more tickers, derived from the underlying sentiment and event data. The fastest way to get a single actionable view.
Get a written market summary
Use GET /v1/insights/analyst/{ticker}
Returns an AI-generated narrative summary of market conditions over a chosen lookback window (weekly, monthly, quarterly, yearly). Designed for discretionary traders who want a written briefing rather than a number.
Build or backtest a quantitative model
Use GET /v1/headlines/index/ticker/historical/{ticker} or GET /v1/headlines/index/gmsi/historical/{country}
Returns hourly sentiment index values for a ticker or model. These are the clean, numeric time-series inputs used in systematic strategies. Historical data is available for backtesting; live data is available for production inference.
Monitor significant market events
Use GET /v1/events/feed/live/ticker/{ticker}
Returns structured events extracted from news — discrete, market-relevant occurrences with a topic, directional label, and timestamp. More structured than raw headlines, more granular than insights.
Track macroeconomic sentiment
Use GET /v1/headlines/index/gmsi/live/{country}
Returns aggregated macro-level sentiment for a given country and topic (e.g. inflation, monetary policy, fiscal policy). Browse countries via GET /v1/countries and topics via GET /v1/headlines/topics/gmsi. Useful for macro overlays on top of asset-level signals.
Get a forward-looking forecast
Use GET /v1/insights/forecast/{ticker}
Returns a directional forecast and scenario summary for a ticker based on Permutable's predictive models.
Discover what tickers and sectors are available
Use GET /v1/ticker/search or GET /v1/sector
/ticker/search lets you search by keyword. /sector returns tickers grouped by sector. Use these before any data call to confirm the ticker ID you need.
Decision summary
| Use case | Recommended endpoint |
|---|---|
| Latest news with sentiment | GET /v1/headlines/feed/live/ticker/{ticker} |
| Directional trading signal | GET /v1/signals |
| Written market briefing | GET /v1/insights/analyst/{ticker} |
| Quantitative index for modelling | GET /v1/headlines/index/ticker/live/{ticker} |
| Structured market events | GET /v1/events/feed/live/ticker/{ticker} |
| Macro sentiment overlay | GET /v1/headlines/index/gmsi/live/{country} |
| Forward-looking forecast | GET /v1/insights/forecast/{ticker} |
| Discover available tickers | GET /v1/ticker/search |
Next steps
- Basics — understand how all these data types fit together in the pipeline
- Systematic Workflow — end-to-end guide for quantitative model integration
- Discretionary Workflow — end-to-end guide for active trading workflows
- API Reference — full parameter details for every endpoint