Energy News Feed

Returns recent energy news headlines with their source, link, excerpt and the commodities, regions and facilities each one mentions. Use it to put context next to a price move, or poll it for new items.

GET/v1/context/market/news

Authentication

See Authentication Guide for API key setup.

Request

curl "https://api.oilpriceapi.com/v1/context/market/news?per_page=2" \
  -H "Authorization: Token YOUR_API_KEY"

There are two ways to read the feed. Without cursor or since it is a recent window: items published in the last hours, newest first, paged with page. With cursor or since it is a poll: items in the order we stored them, with a cursor to pass on the next call.

Parameters

ParameterTypeDefaultDescription
hoursinteger24Recent window only. How far back to look, by publication time. 1 to 2160 (90 days)
per_pageinteger25Items per call. 1 to 100
pageinteger1Recent window only. Page number
commoditystring—Only items that mention this commodity code, e.g. BRENT_CRUDE_USD
regionstring—Only items that mention this region, e.g. persian_gulf
facilitystring—Only items that mention this facility
event_typestring—One of storage_update, pipeline_constraint, lng_operations, production_update, market_update
sentimentstring—Recent window only. One of positive, negative, neutral
summarizedstring—Recent window only. true for items that have a summary, false for items that do not
sincestring—Start a poll: items stored at or after this ISO 8601 timestamp. Must include a timezone and not be in the future
cursorstring—Continue a poll: the meta.next_cursor from the previous call

Send cursor or since, not both. A poll does not accept page, sentiment or summarized. A cursor is bound to the filters it was issued with; changing commodity, region, facility or event_type between calls invalidates it (400); start again with since.

Response

From a live call on 2026-11-13 (one item shown, meta.sources shortened to one of four):

{
  "status": "success",
  "data": [
    {
      "id": "41619c40-2405-40b3-b0f0-eb7a326a5edc",
      "title": "Hydropower generation in the Southwest fell to record lows this summer",
      "source": "eia_today_in_energy",
      "url": "https://www.eia.gov/todayinenergy/detail.php?id=68445",
      "summary": null,
      "source_excerpt": "Prolonged drought conditions affecting the Colorado River Basin led to record low hydropower generation this summer in the Southwestern electricity supply region, which includes Arizona, New Mexico, and small parts of Nevada and California. Hydropower generation from April through August 2026 was 19% lower than during the same period last year and 28% lower than the 10-year average, according to the latest data from our Form EIA-923 survey",
      "content_digest": "48e9ed6f5c48abdc1398403be2c21e9311d1f1b111666bbfd53074f8f6a43243",
      "story_key": "b39ee9482ebbd3866be1abc578c0b07b3e238b90c707637e9c530790f3b96c62",
      "collected_at": "2026-11-13T14:09:22Z",
      "event_type": "market_update",
      "facilities_mentioned": [],
      "supersedes_id": null,
      "effective_at": null,
      "sentiment": null,
      "commodities_mentioned": [],
      "regions_mentioned": [],
      "published_at": "2026-11-13T14:00:00Z"
    }
  ],
  "meta": {
    "sources": [
      {
        "feed_id": "34ca1f79b856ac92",
        "source": "eia_today_in_energy",
        "status": "healthy",
        "last_attempt_at": "2026-11-13T17:39:41Z",
        "last_success_at": "2026-11-13T17:39:41Z"
      }
    ],
    "freshness": "healthy",
    "next_cursor": null,
    "has_more": true
  }
}

Item fields

FieldTypeDescription
idstringItem identifier (UUID)
titlestringHeadline as published
sourcestringSource label. Official publishers are named (for example eia_today_in_energy); others read market_reporting
urlstringLink to the article at its publisher
summarystring or nullShort summary when one has been produced; null otherwise
source_excerptstring or nullThe excerpt the publisher's feed carried
content_digeststringHash of the item's content; changes when the publisher revises it
story_keystringStable key for the story, shared by revisions of the same story
collected_atstringWhen we collected the item (ISO 8601, UTC)
published_atstring or nullWhen the publisher says it was published; null when the feed gave no time
event_typestring or nullOne of the event_type values above
sentimentstring or nullpositive, negative or neutral when classified; null otherwise
commodities_mentionedarrayCommodity codes the item mentions, e.g. ["BRENT_CRUDE_USD"]
regions_mentionedarrayRegions the item mentions, e.g. ["persian_gulf"]
facilities_mentionedarrayFacilities the item mentions
supersedes_idstring or nullid of the earlier item this one replaces, when it is a revision
effective_atnullReserved; currently always null

meta

FieldDescription
sourcesOne entry per feed we collect: feed_id, source, status, last_attempt_at, last_success_at
freshnesshealthy when every feed's status is healthy, otherwise degraded
next_cursorOn a poll, the cursor for the next call. null on a recent-window call
has_moretrue when more items are waiting: fetch the next page, or call again with next_cursor

Polling for new items

Start with since, then keep passing the cursor you were given:

# First call
curl "https://api.oilpriceapi.com/v1/context/market/news?since=2026-11-13T17:00:00Z" \
  -H "Authorization: Token YOUR_API_KEY"

# Every later call
curl "https://api.oilpriceapi.com/v1/context/market/news?cursor=NEXT_CURSOR" \
  -H "Authorization: Token YOUR_API_KEY"

While has_more is true, call again straight away with the new cursor. When it is false you are caught up; keep the cursor and use it on your next poll.

Errors

An out-of-range or malformed parameter returns 400:

{
  "status": "error",
  "error": {
    "code": "INVALID_NEWS_QUERY",
    "message": "hours must be an integer between 1 and 2160"
  }
}

The same code covers an unknown event_type or sentiment, cursor sent together with since, a since without a timezone or in the future, and a cursor that is invalid or was issued for different filters.

Last Updated: