---
title: Historical Commodity Prices, Delivered Simply.
version: 2.0.0
description: OHLC price data for one or more commodities on a specific date, back to January 1990. Falls back to the nearest earlier rate if none exists for the exact date. Monthly-updated commodities only have a closing price — `open`, `high`, and `low` come back as `0`. Unresolved symbols degrade to a 206 partial response instead of failing the whole request.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v2.0
paths: 1
operations: 1
schemas: 4
---

## Table of Contents

- [Historical Commodity Prices, Delivered Simply. v2.0.0](#historical-commodity-prices-delivered-simply-v200)
  - [Authentication](#authentication)
  - [Commodity APIs](#commodity-apis)
    - [getHistoricalCommodityPrices](#gethistoricalcommodityprices)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [HistoricalCommodityPricesResponse](#historicalcommoditypricesresponse)
    - [HistoricalCommodityRates](#historicalcommodityrates)
    - [HistoricalCommodityRate](#historicalcommodityrate)
    - [ErrorResponse](#errorresponse)



# Historical Commodity Prices, Delivered Simply. v2.0.0

OHLC price data for one or more commodities on a specific date, back to January 1990. Falls back to the nearest earlier rate if none exists for the exact date. Monthly-updated commodities only have a closing price — `open`, `high`, and `low` come back as `0`. Unresolved symbols degrade to a 206 partial response instead of failing the whole request.

Base URLs:

* [https://api.apifreaks.com/v2.0](https://api.apifreaks.com/v2.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## Commodity APIs

### getHistoricalCommodityPrices

`GET /commodity/rates/historical`

*Get historical commodity prices*

Returns OHLC price data for the requested commodity symbols on a specific date.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Response format. Currently only `json` is supported.|
|symbols|query|string|true|Comma-separated list of commodity symbols.|
|date|query|string|true|Date in `YYYY-MM-DD` format. Data available from 1990 onwards.|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|

> Example responses

> Successful operation

```json
{
  "success": true,
  "date": "2025-01-10",
  "rates": {
    "WTIOIL-SPOT": {
      "date": "2025-01-10",
      "open": 73.77,
      "high": 77.16,
      "low": 73.55,
      "close": 75.97
    },
    "XAU": {
      "date": "2025-01-10",
      "open": 2669.93,
      "high": 2697.85,
      "low": 2663.61,
      "close": 2689.44
    }
  }
}
```

```json
{
  "success": true,
  "date": "2025-01-10",
  "rates": {
    "NG-EU": {
      "date": "2025-01-01",
      "open": 0,
      "high": 0,
      "low": 0,
      "close": 14.66
    }
  }
}
```

> Partial Content — Some requested symbols could not be resolved

```json
{
  "success": true,
  "date": "2025-01-10",
  "rates": {
    "XAU": {
      "date": "2025-01-10",
      "open": 2669.93,
      "high": 2697.85,
      "low": 2663.61,
      "close": 2689.44
    }
  },
  "unresolved": {
    "FAKESYM": {
      "message": "We don't support this symbol, please visit our symbols page to see supported symbols."
    }
  }
}
```

> Bad Request — Missing parameters or invalid date

```json
{
  "error": "Invalid Param Exception",
  "message": "please pass correct parameters",
  "path": "/v2.0/commodity/rates/historical",
  "status": 400,
  "timestamp": "2026-09-14T08:44:32.013Z"
}
```

```json
{
  "timestamp": "2026-09-14T08:45:13.934Z",
  "path": "/rates/historical",
  "code": 400,
  "error": "VALIDATION_ERROR",
  "message": "Invalid Date Format (YYYY-MM-DD)."
}
```

```json
{
  "timestamp": "2026-09-14T08:44:01.487Z",
  "path": "/rates/historical",
  "code": 400,
  "error": "VALIDATION_ERROR",
  "message": "Invalid Date: The provided date does not exist."
}
```

> Payment Required — Maximum symbols per request exceeded

```json
{
  "timestamp": "2026-09-14T08:44:01.978Z",
  "path": "/rates/historical",
  "code": 402,
  "error": "PAYMENT_REQUIRED",
  "message": "Maximum symbols per request exceeded"
}
```

> Not found - Symbol or rate not available

```json
{
  "timestamp": "2026-09-14T08:44:01.978Z",
  "path": "/rates/historical",
  "code": 404,
  "error": "SYMBOL_NOT_FOUND",
  "message": "The symbol is not supported, please visit the documentation for a list of supported symbols",
  "unresolved": {
    "FAKESYM": {
      "message": "We don't support this symbol, please visit our symbols page to see supported symbols."
    }
  }
}
```

```json
{
  "timestamp": "2026-09-14T08:44:02.528Z",
  "path": "/rates/historical",
  "code": 404,
  "error": "RATE_NOT_FOUND",
  "message": "no rates found for the specified date"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful operation|[HistoricalCommodityPricesResponse](#historicalcommoditypricesresponse)|
|206|[Partial Content](https://tools.ietf.org/html/rfc7233#section-4.1)|Partial Content — Some requested symbols could not be resolved|[HistoricalCommodityPricesResponse](#historicalcommoditypricesresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing parameters or invalid date|[ErrorResponse](#errorresponse)|
|402|[Payment Required](https://tools.ietf.org/html/rfc7231#section-6.5.2)|Payment Required — Maximum symbols per request exceeded|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not found - Symbol or rate not available|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|206|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|402|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### HistoricalCommodityPricesResponse

Historical commodity prices response containing success status, date, and OHLC rate data.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|success|boolean|true|none|`true` for successful requests.|
|date|string|true|none|Date for which prices were fetched (YYYY-MM-DD).|
|rates|[HistoricalCommodityRates](#historicalcommodityrates)|true|none|Object of commodity symbols to their OHLC price data. Each key is a commodity symbol and the value contains date, open, high, low, and close prices.|
|unresolved|object|false|none|Present only on a 206 Partial Content response, when some requested symbols could not be resolved. Map of each unresolved symbol to a detail message and optional close-match suggestions.|
|» **additionalProperties**|object|false|none|none|
|»» message|string|false|none|Detail message explaining why this symbol was not resolved.|
|»» suggestions|[string]|false|none|Optional list of supported symbols that closely match the unresolved symbol.|

### HistoricalCommodityRates

Object of commodity symbols to their OHLC price data. Each key is a commodity symbol and the value contains date, open, high, low, and close prices.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|symbol|[HistoricalCommodityRate](#historicalcommodityrate)|true|none|OHLC price data for a single commodity on a specific date. For monthly-updated commodities, only `close` is meaningful — `open`, `high`, and `low` are returned as `0`.|

### HistoricalCommodityRate

OHLC price data for a single commodity on a specific date. For monthly-updated commodities, only `close` is meaningful — `open`, `high`, and `low` are returned as `0`.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|date|string|true|none|Date for which prices were fetched (YYYY-MM-DD). May differ from the requested `date` when the API falls back to the last available rate before it, or snaps to the first day of the month for monthly-updated commodities.|
|open|number(float)|true|none|Opening price on the given date. `0` for monthly-updated commodities.|
|high|number(float)|true|none|Highest price recorded on the given date. `0` for monthly-updated commodities.|
|low|number(float)|true|none|Lowest price recorded on the given date. `0` for monthly-updated commodities.|
|close|number(float)|true|none|Closing price on the given date.|

### ErrorResponse

Standard error envelope returned by the API on failed requests. Gateway-level validation errors populate status; commodity-service errors (date/symbol/rate validation) populate code instead — check whichever is present.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type (e.g., Invalid Param Exception, VALIDATION_ERROR, SYMBOL_NOT_FOUND, RATE_NOT_FOUND).|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path (gateway errors) or internal service path (commodity-service errors) that produced the error.|
|status|integer|false|none|HTTP status code. Present on gateway-level errors.|
|code|integer|false|none|HTTP status code. Present on commodity-service errors instead of status.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|
|unresolved|object|false|none|Present only on SYMBOL_NOT_FOUND errors. Map of each unresolved symbol to a detail message and optional close-match suggestions.|
|» **additionalProperties**|object|false|none|none|
|»» message|string|false|none|Detail message explaining why this symbol was not resolved.|
|»» suggestions|[string]|false|none|Optional list of supported symbols that closely match the unresolved symbol.|