API Reference
Authentication
Authorization: Token YOUR_API_KEY
Get your API key from oilpriceapi.com/dashboard.
Base URL
https://api.oilpriceapi.com/v1
Response Format
{
"status": "success|error",
"data": { ... },
"meta": {
"request_id": "req_abc123",
"response_time_ms": 42,
"timestamp": "2025-07-18T10:30:00Z"
}
}
Rate Limits
| Plan | Requests/Month | Rate Limit |
|---|---|---|
| Free | 200 | 60 per rolling 60s |
| Developer | 10,000 | 60 per rolling 60s |
| Starter | 50,000 | 60 per rolling 60s |
| Professional | 100,000 | 60 per rolling 60s |
| Scale | 1,000,000 | 60 per rolling 60s |
Headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1736784000
Endpoints
Prices
| Method | Endpoint | Description |
|---|---|---|
| GET | /prices/latest | Latest commodity prices |
| GET | /prices/past_day | Hourly prices (24h) |
| GET | /prices/past_week | Daily prices (7d) |
| GET | /prices/past_month | Daily prices (30d) |
| GET | /prices/past_year | Weekly prices (365d) |
Commodities
| Method | Endpoint | Description |
|---|---|---|
| GET | /commodities | List all commodities |
| GET | /commodities/{code} | Commodity details |
AI Agents (MCP)
| Method | Endpoint | Description |
|---|---|---|
| GET | /market-brief | Multi-commodity snapshot + forecasts (+ optional narrative) |
| GET | /subscriptions | List recurring watches |
| POST | /subscriptions | Create a recurring watch |
| DELETE | /subscriptions/{id} | Delete a watch |
| GET | /subscriptions/events | Poll for new events (no quota cost) |
See the Agent Subscriptions with MCP recipe for the full agent workflow.
Premium Endpoints
| Method | Endpoint | Description | Plan |
|---|---|---|---|
| GET | /prices/all | All 460+ commodities | Professional+ |
| GET | /storage/cushing | Cushing storage data | Professional+ |
| GET | /drilling/overview | Drilling intelligence | Scale |
| GET | /futures/ice-brent | ICE Brent futures | Professional+ |
| GET | /marine-fuels/overview | Marine fuel prices | Professional+ |
Marine Fuels
| Method | Endpoint | Description |
|---|---|---|
| GET | /marine/ports | List fuel ports |
| GET | /marine/ports/{code} | Port details |
| GET | /marine/fuels | All marine fuel prices |
Common Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
by_code | string | Commodity code(s), comma-separated | WTI_USD,BRENT_CRUDE_USD |
page | integer | Pagination page number | 1 |
per_page | integer | Results per page (default: 100) | 100 |
Error Codes
Error shapes vary by status code (see the Error Codes Guide for full JSON bodies):
| Status | Body code | Description |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid API key (error.code) |
| 400 | invalid_code | Unknown commodity code (data.error, with invalid_codes[]) |
| 404 | (empty body) | Unknown route — no JSON returned; check the HTTP status |
| 429 | (rate-limit) | Monthly quota or rate limit exceeded — back off and retry |
See the Error Codes Guide for complete request/response examples.
Interactive API Explorer
- Swagger UI - Full interactive API explorer with "Try it" functionality
- API Explorer - Test endpoints directly