1
Choose a Ticker
Select the energy commodity to use in the examples below.
2
The Endpoint
The Headlines Sentiment Index provides daily aggregated sentiment for any tracked ticker, broken down by topic.
Base URL
https://copilot-api.permutable.ai/v1/headlines/index/ticker/historical/BZ_COM
| Parameter | Value | Description |
|---|
topic_preset | ALL | Return all topic categories |
limit | 1000 | Records per page (max 1000) |
sparse | true | Only dates with headlines |
align_to_period_end | true | Align dates to end of period |
index_type | EXPLICIT | EXPLICIT, IMPLICIT, or COMBINED |
start_date | 2026-02-06 | How far back (max 90 days) |
3
Try It — cURL
Copy and paste this into a terminal. Replace YOUR_API_KEY with your Permutable API key.
Shell
curl -H "x-api-key: YOUR_API_KEY" \
"https://copilot-api.permutable.ai/v1/headlines/index/ticker/historical/BZ_COM?topic_preset=ALL&limit=100&sparse=true&align_to_period_end=true&index_type=EXPLICIT&start_date=2026-02-06"
4
Try It — Python
A minimal script to fetch and print sentiment data.
Python
import requests
url = "https://copilot-api.permutable.ai/v1/headlines/index/ticker/historical/BZ_COM"
params = {
"topic_preset": "ALL",
"limit": 100,
"sparse": "true",
"align_to_period_end": "true",
"index_type": "EXPLICIT",
"start_date": "2026-02-06",
}
headers = {"x-api-key": "YOUR_API_KEY"}
resp = requests.get(url, params=params, headers=headers)
data = resp.json()
for row in data["data"][:5]:
print(row["publication_time"], row["topic_name"],
f"count={row['headline_count']}",
f"sentiment={row['sentiment_sum']:.4f}")
5
Response Structure
Each record contains a daily sentiment aggregate for one topic.
JSON response (truncated)
{
"data": [
{
"publication_time": "2026-03-07T00:00:00+00:00",
"topic_name": "Market Dynamics-Price Moves",
"headline_count": 142,
"sentiment_sum": -3.8721,
"ticker_id": "BZ_COM"
},
// ... more records
],
"has_more": true,
"next_token": "eyJhcGl..." // use for pagination
}
6
Computing the Sentiment Index
The index value shown on the dashboard is the average sentiment per headline:
Python
# For each (topic, date) group:
index_value = sentiment_sum / headline_count
# Ranges roughly from -1 (very negative) to +1 (very positive)
To paginate through all results, keep requesting with the next_token from each response until has_more is false.
7
Available Tickers
This dashboard tracks 8 energy commodity tickers. Use any of these as the {ticker} path parameter.
| Ticker ID | Commodity |
|---|
BZ_COM | Brent Crude Oil |
CL_COM | WTI Crude Oil |
GOIL_COM | Gasoil (ICE) |
HO_COM | Heating Oil (ULSD) |
LNG_COM | LNG |
NG_COM | Henry Hub Natural Gas |
RB_COM | RBOB Gasoline |
TFM_COM | Dutch TTF Natural Gas |