Premium Features and Plan Requirements

Use this guide when you need to answer three practical questions quickly:

1. Which features are available on my current plan?
2. Which endpoints require a paid or premium subscription?
3. What changes do I need to make when upgrading from the free tier?

Plan Matrix

The pricing page is the source of truth for plans, prices and what each plan includes. The table below is its feature comparison as published on 2026-11-13; if the two ever differ, the pricing page is right. For request quotas and minute limits, see the Rate Limiting Guide.

New accounts start with a 7-day trial of 10,000 requests with the full API apart from licensed datasets, then continue on the Free plan.

Notes on the rows customers ask about most:

• History. The history endpoints need a paid plan or an active trial; see Historical Prices for the endpoints and the 2026-11-16 date for /v1/prices/historical. Historical availability varies by dataset, so confirm the commodity and date range you need before choosing a plan.
• Marine and bunker fuels. GET /v1/prices/marine-fuels/latest needs no API key. Bunker codes such as VLSFO_SGSIN_USD are also served by /v1/prices/latest, and their history by /v1/prices/historical on any paid plan, Developer included, within that plan's history depth. The bulk bunker endpoints (/v1/maritime-fuels/*, /v1/bunker-fuels/all and /v1/bunker-fuels/export) are Professional and Scale.
• WebSocket. Included on Professional and Scale; see the WebSocket API.
• Drilling Intelligence and well permits. Scale only.

Premium Endpoints by Capability

Each endpoint's reference page states its own access requirement. These are the ones tied to a plan feature in the table above:

Professional and Scale

• /v1/futures/* (futures data)
• wss://api.oilpriceapi.com/cable (WebSocket)

Scale

• /v1/drilling-intelligence

Access Requirements

All premium features use the same authentication model as the core API:

Authorization: Token YOUR_API_KEY

Premium access is enforced by the account tied to that API key. You do not need a separate hostname or a different auth scheme after upgrading.

Commercial Use and Redistribution

Premium access does not automatically grant public display, raw-data resale, redistribution, or downstream productization rights. Review Data Usage Policy before exposing data outside internal workflows.

Typical Upgrade Path

From Free Trial to Paid

When a trial ends, the most common next step is moving to a paid REST plan:

• Keep the same integration and auth header
• Review any rate-limit changes in Rate Limiting
• Check whether your code relies on trial-only access to premium endpoints
• Replace trial-only assumptions with plan-aware tests

From REST-Only to Premium Data

When enabling premium datasets:

• Add handling for 403 or 402 style access-denied responses during rollout
• Update onboarding or internal docs to list newly available endpoints
• Verify dashboards and background jobs use only features your production key can access

Example: Detecting Tier-Locked Features

curl "https://api.oilpriceapi.com/v1/prices/all" \
  -H "Authorization: Token YOUR_API_KEY"

If your key does not include the required plan, expect an access-denied response with upgrade guidance.

{
  "status": "error",
  "error": {
    "code": "INSUFFICIENT_PLAN",
    "message": "This endpoint requires a higher-tier subscription.",
    "required_tier": "professional"
  }
}

The exact shape may vary by endpoint, but integrations should treat plan failures as non-retryable until the account is upgraded.

Data Freshness by Capability

Data freshness differs by product line:

For source-specific expectations, see Data Freshness and the relevant endpoint page.

Development and Testing

When testing premium features in staging or CI:

• Use a dedicated API key for the exact plan you want to exercise
• Keep free-tier and premium-tier tests separate
• Do not assume trial access matches long-term paid entitlements
• Mock INSUFFICIENT_PLAN responses in client libraries and UI tests

Related Docs

• Currency Conversion
• Data Usage Policy
• Plan Fit
• WebSocket API
• Premium All Prices Endpoint
• Drilling Intelligence
• Rate Limiting