---
title: Commodity Fluctuation API 
version: 2.0.0
description: Price change and percentage movement for one or more commodities over a custom date range, with no limit on range length. For monthly-updated commodities the range snaps to month boundaries. 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: 3
---

## Table of Contents

- [Commodity Fluctuation API  v2.0.0](#commodity-fluctuation-api-v200)
  - [Authentication](#authentication)
  - [Commodity APIs](#commodity-apis)
    - [getCommodityFluctuation](#getcommodityfluctuation)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [CommodityFluctuationResponse](#commodityfluctuationresponse)
    - [CommodityFluctuationRates](#commodityfluctuationrates)
    - [ErrorResponse](#errorresponse)



# Commodity Fluctuation API  v2.0.0

Price change and percentage movement for one or more commodities over a custom date range, with no limit on range length. For monthly-updated commodities the range snaps to month boundaries. 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

### getCommodityFluctuation

`GET /commodity/fluctuation`

*Get commodity price fluctuations*

Returns price fluctuation metrics (start, end, change, percent change) for the requested commodity symbols over 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.|

##### Enumerated Values

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

> Example responses

> Successful operation

```json
{
  "success": true,
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "rates": {
    "WTIOIL-SPOT": {
      "startRate": 72.02,
      "endRate": 75.81,
      "change": 3.79,
      "changePercent": 5.26
    },
    "XAU": {
      "startRate": 2063.63,
      "endRate": 2039.83,
      "change": -23.8,
      "changePercent": -1.15
    }
  }
}
```

> Partial Content — Some requested symbols could not be resolved

```json
{
  "success": true,
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "rates": {
    "XAU": {
      "startRate": 2063.63,
      "endRate": 2039.83,
      "change": -23.8,
      "changePercent": -1.15
    }
  },
  "unresolved": {
    "FAKESYM": {
      "message": "We don't support this symbol, please visit our symbols page to see supported symbols."
    }
  }
}
```

> Bad Request — Missing parameters or invalid dates

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

```json
{
  "timestamp": "2026-07-27T11:37:22.687Z",
  "path": "/rates/fluctuation",
  "code": 400,
  "error": "VALIDATION_ERROR",
  "message": "Invalid Date Format (YYYY-MM-DD)."
}
```

```json
{
  "timestamp": "2026-07-27T11:37:33.565Z",
  "path": "/rates/fluctuation",
  "code": 400,
  "error": "VALIDATION_ERROR",
  "message": "Invalid Date: The provided start date or end date does not exist."
}
```

```json
{
  "timestamp": "2026-07-27T11:37:23.206Z",
  "path": "/rates/fluctuation",
  "code": 400,
  "error": "VALIDATION_ERROR",
  "message": "Start date cannot be after end date"
}
```

> Payment Required — Maximum symbols per request exceeded

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

> Not found - Symbol or data not available

```json
{
  "timestamp": "2026-09-14T08:43:48.408Z",
  "path": "/rates/fluctuation",
  "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.022Z",
  "path": "/rates/fluctuation",
  "code": 404,
  "error": "DATA_NOT_FOUND",
  "message": "No data found for the given date range"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful operation|[CommodityFluctuationResponse](#commodityfluctuationresponse)|
|206|[Partial Content](https://tools.ietf.org/html/rfc7233#section-4.1)|Partial Content — Some requested symbols could not be resolved|[CommodityFluctuationResponse](#commodityfluctuationresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing parameters or invalid dates|[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

### CommodityFluctuationResponse

Commodity fluctuation response containing price change data per symbol over a date range.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|success|boolean|true|none|`true` for successful requests.|
|startDate|string|true|none|Start date of the interval (YYYY-MM-DD).|
|endDate|string|true|none|End date of the interval (YYYY-MM-DD).|
|rates|[CommodityFluctuationRates](#commodityfluctuationrates)|true|none|Map of requested commodity symbols to their fluctuation metrics. Each key is a commodity symbol (e.g. XAU).|
|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.|

### CommodityFluctuationRates

Map of requested commodity symbols to their fluctuation metrics. Each key is a commodity symbol (e.g. XAU).

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|CommodityFluctuationItem|object|false|none|Fluctuation metrics for a single commodity over a date range.|
|» startRate|number(float)|true|none|Price of the commodity on the start date.|
|» endRate|number(float)|true|none|Price of the commodity on the end date.|
|» change|number(float)|true|none|Absolute price difference between end and start dates. May be negative.|
|» changePercent|number(float)|true|none|Percentage price change from start to end date. May be negative.|

### 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.|