---
title: Historical Exchange Rate API Reference
version: 1.0.0
description: Get exchange rates for a specific historical date for any base currency. Returns rates for all available currencies or a filtered set of symbols. Supports fiat, crypto, and metals. Accepts a date in YYYY-MM-DD format. Returns a 400 error for a missing/malformed date and a 404 error for unsupported currencies, symbols, or a date with no available data.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 2
---

## Table of Contents

- [Historical Exchange Rate API Reference v1.0.0](#historical-exchange-rate-api-reference-v100)
  - [Authentication](#authentication)
  - [Currency APIs](#currency-apis)
    - [getHistoricalExchangeRates](#gethistoricalexchangerates)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [HistoricalExchangeRatesResponse](#historicalexchangeratesresponse)
    - [ErrorResponse](#errorresponse)



# Historical Exchange Rate API Reference v1.0.0

Get exchange rates for a specific historical date for any base currency. Returns rates for all available currencies or a filtered set of symbols. Supports fiat, crypto, and metals. Accepts a date in YYYY-MM-DD format. Returns a 400 error for a missing/malformed date and a 404 error for unsupported currencies, symbols, or a date with no available data.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.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.

## Currency APIs

### getHistoricalExchangeRates

`GET /currency/rates/historical`

*Get historical exchange rates*

Returns exchange rates for a specific historical date.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Response format: `json` (default) or `xml`.|
|base|query|string|false|Base currency code. Defaults to `USD`. Supports fiat, crypto, and metals.|
|symbols|query|string|false|Comma-separated currency codes. Omit to get all available rates.|
|date|query|string|true|Historical date in `YYYY-MM-DD` format.|

##### Enumerated Values

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

> Example responses

> Successful operation

```json
{
  "date": "2025-01-10",
  "base": "USD",
  "rates": {
    "EUR": "0.9762",
    "PKR": "278.65"
  }
}
```

> Bad Request — Missing or malformed date

```json
{
  "error": "Invalid Param Exception",
  "message": "please pass correct parameters",
  "path": "/v1.0/currency/rates/historical",
  "status": 400,
  "timestamp": "2026-07-27T12:01:57.285Z"
}
```

```json
{
  "timestamp": 1785153717794,
  "status": 400,
  "error": "Invalid Param Exception",
  "message": "Provided Date 10-01-2025 is in invalid format. It should be like  YYYY-MM-DD!",
  "path": "/v2.0/rates/historical"
}
```

> Not found - Currency, symbol, or date not available

```json
{
  "timestamp": 1785153718397,
  "status": 404,
  "error": "Not Found Exception",
  "message": "Rates of provided date 2099-01-01 are not available in our database.",
  "path": "/v2.0/rates/historical"
}
```

```json
{
  "timestamp": 1785153718975,
  "status": 404,
  "error": "Not Found Exception",
  "message": "Rates of provided currency ZZZ are not available in our database!",
  "path": "/v2.0/rates/historical"
}
```

```json
{
  "timestamp": 1785153718975,
  "status": 404,
  "error": "Not Found Exception",
  "message": "Rates of provided Symbols are not available in our database!",
  "path": "/v2.0/rates/historical"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful operation|[HistoricalExchangeRatesResponse](#historicalexchangeratesresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing or malformed date|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not found - Currency, symbol, or date 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.|
|400|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

### HistoricalExchangeRatesResponse

Historical exchange rate response containing date, base currency, and rates map.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|date|string|true|none|The requested historical date (YYYY-MM-DD).|
|base|string|true|none|Base currency used for calculating exchange rates.|
|rates|object|true|none|Map of currency codes to their exchange rate against the base currency on the requested date. Each key is a currency code and the value is an exchange rate string.|
|» ExchangeRateString|string|false|none|Exchange rate value as a string for this currency code.|

### ErrorResponse

Standard error envelope returned by the API on failed requests. Gateway-level validation errors use an ISO 8601 timestamp and the public endpoint path; currency-service errors (date/symbol validation) use a Unix millisecond timestamp and an internal service path instead.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type (e.g., Invalid Param Exception, Not Found Exception).|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path (gateway errors) or internal service path (currency-service errors) that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string | integer|false|none|Timestamp when the error occurred — ISO 8601 string for gateway errors, Unix milliseconds integer for currency-service errors.|