Macro event history
Release history of one event (start_date, end_date, limit); unknown names return an empty array
GET
/openapi/v1/macro/events/{event}/historyRefresh: 1 min
Returns the release history for one macroeconomic event, newest first.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| event | string | Required | Event name exactly as returned by GET /macro/events, URL-encoded. e.g. CPI%20(YoY), S%26P%20Global%20Services%20PMI |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| start_date | string | Optional | Start date, yyyy-MM-dd (inclusive) |
| end_date | string | Optional | End date, yyyy-MM-dd (inclusive) |
| limit | integer | Optional | Default 50, maximum 100. Values above the maximum are silently clamped |
Request Example
curl "https://openapi.sosovalue.com/openapi/v1/macro/events/CPI%20(YoY)/history?limit=12" \ -H "x-soso-api-key: $SOSO_API_KEY"
Response Example
[
{
"date": "2026-07-14",
"actual": "3.5%",
"forecast": "3.8%",
"previous": "4.2%"
},
{
"date": "2026-08-05",
"actual": "",
"forecast": "53.6",
"previous": "51.2"
}
]Response Fields
| Field | Type | Description |
|---|---|---|
| date | String | Release date, yyyy-MM-dd |
| actual | String | Actual value. Empty string "" when not yet released |
| forecast | String | Consensus forecast. Empty string when unavailable |
| previous | String | Previous release value |
Value format — read before parsing
actual / forecast / previous are strings, not numbers, and the unit is embedded in the string and varies by event:
| Event | Sample values | Unit |
|---|---|---|
CPI (YoY), CPI (MoM), Core CPI (MoM), PPI (MoM) | "3.5%", "-0.3%", "0%" | percent, with % suffix |
S&P Global Services PMI, ISM Non-Manufacturing PMI | "53.6", "54" | index points, no suffix |
Existing Home Sales | "4.09" | millions of units, no suffix |
Nonfarm Payrolls | "88" | thousands of jobs, no suffix |
Strip the suffix before converting:
const num = value === "" ? null : Number(value.replace("%", ""));A not-yet-released value is "", not null. Number("") evaluates to 0 in JavaScript, so testing for the empty string first is required — otherwise an unreleased figure silently becomes zero.
Ordering and behaviour
| Behaviour | Value |
|---|---|
| Row order | Newest first (descending by date) |
| Default rows | 50 |
| Maximum rows | 100 (higher values clamped, no error) |
| Date filters | start_date / end_date both work and are inclusive |
| Unknown event name | HTTP 200 with data: [] — not a 404 |
The last row differs from the Chart Data endpoint, which returns
404 / 400401 for an unknown chart. For macro events, an empty array means either "no releases in range" or "event name not recognised" — verify the name against GET /macro/events.Future-dated rows may appear (a scheduled release with forecast and previous populated but actual empty).
Examples
# Latest 12 CPI (YoY) releases curl -sS -H 'x-soso-api-key: YOUR_KEY' \ 'https://openapi.sosovalue.com/openapi/v1/macro/events/CPI%20(YoY)/history?limit=12' # First half of 2026 only curl -sS -H 'x-soso-api-key: YOUR_KEY' \ 'https://openapi.sosovalue.com/openapi/v1/macro/events/PPI%20(MoM)/history?start_date=2026-01-01&end_date=2026-06-30' # Event name containing "&" — encode as %26 curl -sS -H 'x-soso-api-key: YOUR_KEY' \ 'https://openapi.sosovalue.com/openapi/v1/macro/events/S%26P%20Global%20Services%20PMI/history?limit=5'