# US Energy Prices API (EIA): gasoline, diesel, power, stocks (`bosco_labs/us-energy-prices`) Actor

Latest value, change and history of official US energy data from the EIA: weekly gasoline and diesel prices by state, monthly electricity prices by state and sector, crude, fuel and gas stocks, oil output, refinery use. Ask by plain name (gasoline_retail:CA). A source link per series.

- **URL**: https://apify.com/bosco_labs/us-energy-prices.md
- **Developed by:** [Bosco Labs](https://apify.com/bosco_labs) (community)
- **Features:** Limited permissions
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 series

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## US Energy Prices API (EIA): gasoline, diesel, power, stocks

**Ask for US energy data by plain name and get the latest value, the change and the recent
history.** Weekly retail gasoline and diesel prices (US, regions, 9 states), monthly
electricity prices for every state and sector, and the weekly crude, gasoline, distillate and
natural gas stock reports, straight from the U.S. Energy Information Administration. No EIA
API key needed. Built for **AI agents** and for anyone who needs a quick, sourced number.

**Pricing (pay per event):** $0.002 per series returned ($2 per 1,000). A series with no data
and the catalogue are free; an unknown name fails in a second and costs nothing. The same data
is free at eia.gov with your own API key; you pay for the keyless plain-name lookup, the
latest/previous/change summary and the hosted API.

### What you get

One JSON item per series. Real output for `{"series": ["gasoline_retail"], "last": 3}`
(8 Nov 2026):

```json
{
  "schema_version": "1",
  "series": "gasoline_retail:US",
  "title": "U.S. Regular All Formulations Retail Gasoline Prices (Dollars per Gallon)",
  "description": "Weekly regular gasoline retail price in United States (Mondays), all formulations, including taxes.",
  "source": "EIA",
  "route": "petroleum/pri/gnd",
  "series_id": "EMM_EPMR_PTE_NUS_DPG",
  "frequency": "weekly",
  "unit": "USD per gallon",
  "latest_date": "2026-11-02",
  "latest_value": 4.153,
  "previous_date": "2026-10-26",
  "previous_value": 4.269,
  "change": -0.116,
  "observations": [
    { "date": "2026-10-19", "value": 4.284 },
    { "date": "2026-10-26", "value": 4.269 },
    { "date": "2026-11-02", "value": 4.153 }
  ],
  "observation_count": 3,
  "source_url": "https://www.eia.gov/dnav/pet/hist/LeafHandler.ashx?n=PET&s=EMM_EPMR_PTE_NUS_DPG&f=W",
  "provided_by": "Bosco Labs (boscolabs.dev)",
  "api_url": "https://api.eia.gov/v2/petroleum/pri/gnd/data/?frequency=weekly&data%5B0%5D=value&facets%5Bseries%5D%5B%5D=EMM_EPMR_PTE_NUS_DPG&sort%5B0%5D%5Bcolumn%5D=period&sort%5B0%5D%5Bdirection%5D=desc&length=4",
  "attribution": "Source: U.S. Energy Information Administration (EIA), eia.gov open data. Values are reproduced unmodified. The `change` field is computed by Bosco Labs (latest_value - previous_value) and is not an EIA figure. Bosco Labs is not affiliated with or endorsed by EIA.",
  "warnings": [],
  "error": null,
  "retrieved_at": "2026-11-08T21:53:03+00:00",
  "duration_seconds": 6.29
}
```

So: regular gasoline averaged $4.153 a gallon in the week of 2 November 2026, down 11.6 cents.

- **latest / previous / change**: the newest value, the one before it, and the difference.
  `change` is the only value we compute; everything else is EIA's own.
- **observations**: the newest 12 by default, oldest first.
- **source_url** and **api_url**: the series page on eia.gov, and the exact API query (add
  your own `api_key` to re-run it).
- **error**: a series with no data (e.g. diesel for a state EIA doesn't survey) comes back as
  a row with `error` saying why. It is not charged, and the other series are still delivered.

### Series catalogue

| Name | What | Unit | Frequency |
|---|---|---|---|
| `gasoline_retail[:<area>]` | Regular gasoline retail price, all formulations, incl. taxes. Area: `US` (default), `PADD1`-`PADD5` (or `east_coast`, `midwest`, `gulf_coast`, `rocky_mountain`, `west_coast`), `CA`, `CO`, `FL`, `MA`, `MN`, `NY`, `OH`, `TX`, `WA` | USD per gallon | weekly (Mondays) |
| `diesel_retail[:<area>]` | No. 2 diesel retail price. Area: `US`, `PADD1`-`PADD5`, `CA` | USD per gallon | weekly |
| `electricity_price[:<state>[:<sector>]]` | Average retail electricity price. State: `US` (default) or any 2-letter code incl. `DC`; sector `ALL` (default), `RES`, `COM`, `IND`, `TRA` | US cents per kWh | monthly, ~2-month lag |
| `crude_stocks` | US commercial crude oil stocks, excl. SPR | thousand barrels | weekly |
| `spr_stocks` | Strategic Petroleum Reserve | thousand barrels | weekly |
| `gasoline_stocks` | US total motor gasoline stocks | thousand barrels | weekly |
| `distillate_stocks` | US distillate fuel oil stocks (diesel, heating oil) | thousand barrels | weekly |
| `crude_production` | US crude oil field production (weekly estimate) | thousand barrels per day | weekly |
| `refinery_utilization` | US refinery utilization | % of operable capacity | weekly |
| `gas_storage` | Natural gas in underground storage, Lower 48 (working gas) | billion cubic feet | weekly |

`{"mode": "catalogue"}` returns this list as data, for free.

**Not included:** WTI, Brent and Henry Hub spot or futures prices. EIA publishes them under
licence from Refinitiv and NYMEX, so we don't resell them; asking for `wti` fails at once,
free, with that reason.

### Input

```json
{ "series": ["gasoline_retail", "crude_stocks", "electricity_price:TX"] }
```

| Field | Meaning |
|---|---|
| `series` | Plain names from the catalogue, up to 20 per run |
| `last` | Observations per series. Default 12, or the whole date window (max 1000) when `dateFrom` is set |
| `dateFrom`, `dateTo` | Optional window, `YYYY-MM-DD`. `dateTo` + `last: 1` = the value on that date (or the last one before it) |
| `mode` | `series` (default) or `catalogue` |

Typical questions and the input that answers them:

| Question | Input |
|---|---|
| What does gas cost in California this week, vs the US? | `{"series": ["gasoline_retail:CA", "gasoline_retail"], "last": 2}` ($5.748 vs $4.153, week of 2 Nov 2026) |
| Did US crude inventories rise or fall last week? | `{"series": ["crude_stocks"], "last": 2}` (409.8 million barrels, down 0.9 million, week to 30 Oct 2026) |
| What do Texas households pay for power? | `{"series": ["electricity_price:TX:RES"], "last": 1}` (15.91 cents/kWh, August 2026) |
| Diesel price on the West Coast in 2026 | `{"series": ["diesel_retail:PADD5"], "dateFrom": "2026-01-01"}` |

### Use from an AI agent (MCP)

Agents can call this Actor as a tool through the
[Apify MCP server](https://github.com/apify/apify-mcp-server). Add this server URL to your MCP
client (Claude, Cursor, VS Code, ...):

```text
https://mcp.apify.com?tools=bosco_labs/us-energy-prices
```

It loads this Actor as a tool, plus the tools that read its results (`get-actor-run`,
`get-dataset-items`). The hosted server signs you in with OAuth, or accepts your Apify token as
`Authorization: Bearer <APIFY_TOKEN>`.

Example prompt: *"How much did US gasoline and diesel prices change last week, and how full
is natural gas storage? Cite the source."* The agent passes:

```json
{ "series": ["gasoline_retail", "diesel_retail", "gas_storage"], "last": 2 }
```

**Output for agents:** one small JSON item per series (about 2 KB with the default 12
observations), stable `snake_case` fields, numbers as numbers, ISO dates, `null` for unknown,
a source link and the API query per series. Unknown names fail at once with "did you mean"
suggestions. 14 series take about 6 seconds.

**Cost:** $0.002 per series returned, billed to the Apify account the MCP server is signed in
with. Error rows and the catalogue are free.

### FAQ

**How fresh is it?** Live: every call reads the EIA API. Retail gasoline and diesel prices
are surveyed on Mondays and published Monday evening or Tuesday. Petroleum stocks, production
and refinery use come from the Weekly Petroleum Status Report (Wednesdays), gas storage from
the Weekly Natural Gas Storage Report (Thursdays). Monthly electricity prices lag about two
months. Federal holidays shift the schedule.

**Why no WTI or Brent price?** See "Not included" above: those are licensed vendor prices.

**Why no diesel price for Texas?** EIA's weekly diesel survey covers the US, the five PADD
regions and California only; other areas come back as a free error row.

**Do I need an EIA API key?** No. We call EIA with our own key; it never appears in the
output or logs.

**Can I republish the values?** EIA data is US government work in the public domain. Name
EIA as the source (each row has an `attribution`), don't present changed values as EIA's,
and don't imply EIA endorses you. Our `change` field is marked as computed by Bosco Labs.

**Personal data?** None. National, regional and state aggregates only.

# Actor input Schema

## `series` (type: `array`):

Which series to fetch, by plain name (case-insensitive), up to 20 per run, e.g. \["gasoline_retail:CA", "crude_stocks", "electricity_price:TX:RES"]. Names: gasoline_retail\[:<area>] and diesel_retail\[:<area>] (USD/gallon, weekly; area US (default), PADD1-PADD5, or CA, CO, FL, MA, MN, NY, OH, TX, WA; diesel US, PADD1-5, CA), electricity_price\[:<state>\[:<sector>]] (cents/kWh, monthly; state US (default) or a 2-letter code; sector ALL (default), RES, COM, IND, TRA), crude_stocks, spr_stocks, gasoline_stocks, distillate_stocks (thousand barrels, weekly), crude_production (thousand barrels/day, weekly), gas_storage (Bcf, weekly), refinery_utilization (%, weekly). Not offered: WTI/Brent/Henry Hub spot prices (licensed third-party data at EIA). An unknown name fails at once with suggestions and costs nothing. Empty = list the catalogue for free.

## `last` (type: `integer`):

How many of the newest observations to return per series, e.g. 12 (12 weeks of a weekly series). Empty = 12, or with dateFrom every observation in the window (up to 1000). latest_value, previous_value and change are always filled. The price is the same for any number.

## `dateFrom` (type: `string`):

First date of the window, YYYY-MM-DD, e.g. "2026-01-01". For monthly series the month holding the date counts. Empty = no lower bound (only `last` limits).

## `dateTo` (type: `string`):

Last date of the window, YYYY-MM-DD, e.g. "2026-03-15". With last = 1 you get the value on that date or the last one before it. Empty = up to the latest published value.

## `mode` (type: `string`):

"series" (default) fetches the series above. "catalogue" returns one row per supported name pattern with its EIA route, series id, frequency, unit and an example, free of charge.

## Actor input object example

```json
{
  "series": [
    "gasoline_retail",
    "crude_stocks",
    "electricity_price:TX"
  ],
  "mode": "series"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "series": [
        "gasoline_retail",
        "crude_stocks",
        "electricity_price:TX"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("bosco_labs/us-energy-prices").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "series": [
        "gasoline_retail",
        "crude_stocks",
        "electricity_price:TX",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("bosco_labs/us-energy-prices").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "series": [
    "gasoline_retail",
    "crude_stocks",
    "electricity_price:TX"
  ]
}' |
apify call bosco_labs/us-energy-prices --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bosco_labs/us-energy-prices"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Ra2d5TFYzbbErgirs/builds/cVzy7ePOCa004XR7P/openapi.json