Authorization: Token YOUR_API_KEY
Get your API key from oilpriceapi.com/dashboard.
https://api.oilpriceapi.com/v1
{
"status": "success|error",
"data": { ... },
"meta": {
"request_id": "req_abc123",
"response_time_ms": 42,
"timestamp": "2025-07-18T10:30:00Z"
}
}
| Plan | Request Quota | Request Rate Limit |
|---|
| Free | 50 / day | 60 per rolling 60s |
| Free Trial (7 days) | 10,000 | 60 per rolling 60s |
| Developer | 10,000 / month | 60 per rolling 60s |
| Starter | 50,000 / month | 60 per rolling 60s |
| Professional | 100,000 / month | 60 per rolling 60s |
| Scale | 1,000,000 / month | 60 per rolling 60s |
Current tier limits are machine-readable at GET https://api.oilpriceapi.com/v1/meta/limits (no key required); this table is rendered from it at build time. Read limits from the endpoint rather than hardcoding them.
Headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1736784000
See the Agent Subscriptions with MCP recipe for the full agent workflow.
See Premium Features and Plan Requirements for a plan-by-plan matrix and upgrade guidance.
| Parameter | Type | Description | Example |
|---|
by_code | string | Commodity code(s), comma-separated | WTI_USD,BRENT_CRUDE_USD |
currency | string | Convert supported price responses to USD, EUR, or GBP | EUR |
fields | string | Specific fields to return | price,timestamp |
page | integer | Pagination page number | 1 |
per_page | integer | Results per page (default: 100) | 100 |
See Currency Conversion for endpoint coverage and example responses.
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) | Rolling rate limit exceeded (RATE_LIMIT_EXCEEDED) — back off and retry; on paid plans and trials an exhausted quota also uses 429 (MONTHLY_QUOTA_EXCEEDED / TRIAL_LIMIT_EXCEEDED), so branch on error_code |
| 402 | (quota) | Free-tier daily quota exhausted (PAYMENT_REQUIRED) — check reset.date or plan |
See the Error Codes Guide for complete request/response examples.