--- title: Commodities Time Series API version: 2.0.0 description: Daily OHLC history for one or more commodities over a date range of up to 365 days, indexed by date. Non-trading days are excluded. 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 - [Commodities Time Series API v2.0.0](#commodities-time-series-api-v200) - [Authentication](#authentication) - [Commodity APIs](#commodity-apis) - [getCommodityTimeSeries](#getcommoditytimeseries) - [Parameters](#parameters) - [Responses](#responses) - [Schemas](#schemas) - [CommodityTimeSeriesResponse](#commoditytimeseriesresponse) - [CommodityTimeSeriesRates](#commoditytimeseriesrates) - [CommodityOhlc](#commodityohlc) - [ErrorResponse](#errorresponse) # Commodities Time Series API v2.0.0 Daily OHLC history for one or more commodities over a date range of up to 365 days, indexed by date. Non-trading days are excluded. 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 ### getCommodityTimeSeries `GET /commodity/time-series` *Get commodity price time series* Returns day-by-day OHLC data for the requested commodity symbols within a date range. #### 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.| |startDate|query|string|true|Start date in `YYYY-MM-DD` format.| |endDate|query|string|true|End date in `YYYY-MM-DD` format. Maximum range is 365 days.| ##### Enumerated Values |Parameter|Value| |---|---| |format|json| > Example responses > Successful operation ```json { "success": true, "startDate": "2025-01-06", "endDate": "2025-01-08", "rates": { "2025-01-06": { "XAU": { "open": 2649.01, "high": 2651.33, "low": 2645.36, "close": 2646.91 } }, "2025-01-07": { "XAU": { "open": 2662.45, "high": 2663.06, "low": 2655.66, "close": 2658.9 } }, "2025-01-08": { "XAU": { "open": 2669.69, "high": 2674.68, "low": 2668.58, "close": 2671.8 } } } } ``` ```json { "success": true, "startDate": "2025-01-01", "endDate": "2025-03-01", "rates": { "2025-01-01": { "NG-EU": { "open": 0, "high": 0, "low": 0, "close": 14.66 } }, "2025-02-01": { "NG-EU": { "open": 0, "high": 0, "low": 0, "close": 15.34 } }, "2025-03-01": { "NG-EU": { "open": 0, "high": 0, "low": 0, "close": 13.24 } } } } ``` > Partial Content — Some requested symbols could not be resolved ```json { "success": true, "startDate": "2025-01-06", "endDate": "2025-01-08", "rates": { "2025-01-06": { "XAU": { "open": 2649.01, "high": 2651.33, "low": 2645.36, "close": 2646.91 } }, "2025-01-07": { "XAU": { "open": 2662.45, "high": 2663.06, "low": 2655.66, "close": 2658.9 } }, "2025-01-08": { "XAU": { "open": 2669.69, "high": 2674.68, "low": 2668.58, "close": 2671.8 } } }, "unresolved": { "FAKESYM": { "message": "We don't support this symbol, please visit our symbols page to see supported symbols." } } } ``` > Bad Request — Missing parameters, invalid dates, or date range exceeded ```json { "error": "Invalid Param Exception", "message": "please pass correct parameters", "path": "/v2.0/commodity/time-series", "status": 400, "timestamp": "2026-09-14T08:43:58.547Z" } ``` ```json { "timestamp": "2026-07-27T11:38:41.234Z", "path": "/rates/time-series", "code": 400, "error": "VALIDATION_ERROR", "message": "Invalid Date: The provided start date or end date does not exist." } ``` ```json { "timestamp": "2026-07-27T11:38:41.234Z", "path": "/rates/time-series", "code": 400, "error": "VALIDATION_ERROR", "message": "start date cannot be after end date" } ``` ```json { "timestamp": "2026-07-27T11:38:40.699Z", "path": "/rates/time-series", "code": 400, "error": "VALIDATION_ERROR", "message": "Date range exceeds the allowed limit." } ``` > Payment Required — Maximum symbols per request exceeded ```json { "timestamp": "2026-09-14T08:44:00.586Z", "path": "/rates/time-series", "code": 402, "error": "PAYMENT_REQUIRED", "message": "Maximum symbols per request exceeded" } ``` > Not found - Symbol or data not available ```json { "timestamp": "2026-09-14T08:44:00.586Z", "path": "/rates/time-series", "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:31.547Z", "path": "/rates/time-series", "code": 404, "error": "DATA_NOT_FOUND", "message": "No data found for the specified date range" } ``` #### Responses |Status|Meaning|Description|Schema| |---|---|---|---| |200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful operation|[CommodityTimeSeriesResponse](#commoditytimeseriesresponse)| |206|[Partial Content](https://tools.ietf.org/html/rfc7233#section-4.1)|Partial Content — Some requested symbols could not be resolved|[CommodityTimeSeriesResponse](#commoditytimeseriesresponse)| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing parameters, invalid dates, or date range exceeded|[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 data 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 ### CommodityTimeSeriesResponse Commodity time series response containing date-indexed OHLC data per symbol. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |success|boolean|true|none|`true` for successful requests.| |startDate|string|true|none|Start date of the time series (YYYY-MM-DD).| |endDate|string|true|none|End date of the time series (YYYY-MM-DD).| |rates|[CommodityTimeSeriesRates](#commoditytimeseriesrates)|true|none|Map of trading dates to per-symbol OHLC data. Each key is a trading date (YYYY-MM-DD); non-trading days are excluded.| |unresolved|object|false|none|Present only on a 206 Partial Content response, when some requested symbols could not be resolved on any date in the range. 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.| ### CommodityTimeSeriesRates Map of trading dates to per-symbol OHLC data. Each key is a trading date (YYYY-MM-DD); non-trading days are excluded. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |CommodityTimeSeriesSymbolData|object|false|none|Map of commodity symbols to their OHLC data for a single trading date. Each key is a commodity symbol (e.g. XAU).| |» **additionalProperties**|[CommodityOhlc](#commodityohlc)|false|none|OHLC price data for a single commodity on a single trading day. For monthly-updated commodities, only `close` is meaningful — `open`, `high`, and `low` are returned as `0`.| ### CommodityOhlc OHLC price data for a single commodity on a single trading day. For monthly-updated commodities, only `close` is meaningful — `open`, `high`, and `low` are returned as `0`. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |open|number(float)|true|none|Opening price on the given date. `0` for monthly-updated commodities.| |high|number(float)|true|none|Highest price on the given date. `0` for monthly-updated commodities.| |low|number(float)|true|none|Lowest price 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/data 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, DATA_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.|