Carrier Fuel Surcharge History

Get the weekly historical series of a carrier's published fuel-surcharge percentage. Each point is one weekly effective date, with the DOE diesel price and matched band that produced it.

Newly launched

This endpoint is newly launched. See the Fuel Surcharge overview for carrier coverage and plan availability.

Endpoint

GET /v1/fuel-surcharge/{carrier}/history

Authentication

This endpoint requires authentication. Include your API key in the request header:

Authorization: Token YOUR_API_KEY

Available on all plans, including the free tier. Usage counts against your plan's monthly request limit.

Path Parameters

Parameter	Type	Required	Description
`carrier`	string	Yes	Carrier code, e.g. `odfl` (see the carrier code table)

Query Parameters

Parameter	Type	Required	Description	Default
`page`	integer	No	Page number for pagination	`1`
`per_page`	integer	No	Results per page (max: 100)	`100`

This endpoint follows the same 100-point pagination convention as the other time-window endpoints: responses return at most 100 points per page (per_page=100); page through longer series with page=N. Since the series is weekly, one page covers roughly two years of history.

Response

{
  "status": "success",
  "data": {
    "history": [
      {
        "carrier": "odfl",
        "carrier_name": "Old Dominion Freight Line",
        "mode": "ltl",
        "surcharge_percent": 33.9,
        "effective_date": "2026-07-13",
        "doe_diesel_price": 3.756,
        "diesel_band": { "min": 3.7, "max": 3.79 },
        "source": "https://www.odfl.com/us/en/resources/fuel-surcharge.html",
        "retrieved_at": "2026-07-15T12:00:00Z"
      }
      // ... one entry per weekly effective date
    ]
  }
}

Each entry has the same shape as the latest endpoint response.

Examples

curl

curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.oilpriceapi.com/v1/fuel-surcharge/odfl/history?page=1&per_page=100"

Python

import requests

response = requests.get(
    'https://api.oilpriceapi.com/v1/fuel-surcharge/odfl/history',
    headers={
        'Authorization': 'Token YOUR_API_KEY',
        'Accept': 'application/json'
    },
    params={'page': 1, 'per_page': 100}
)
data = response.json()

for point in data['data']['history']:
    print(f"{point['effective_date']}: {point['surcharge_percent']}%")

Data Provenance

We track the fuel-surcharge schedule each carrier publishes; every response includes source and retrieved_at. Historical points keep the effective_date and retrieved_at recorded when each value was retrieved.

Error Responses

Status Code	Description
401	Unauthorized - Invalid or missing API key
404	Not Found - Unknown carrier code
429	Too Many Requests - Rate limit exceeded

/v1/fuel-surcharge - All covered carriers with latest surcharge
/v1/fuel-surcharge/{carrier}/latest - Current surcharge for one carrier