---
title: Currency Time Series - Historical Currency Exchange Rates for a Time Interval
version: 1.0.0
description: Retrieve day-by-day historical exchange rates for any base currency over a custom date range up to 1 year. Returns an array of daily rate objects, each containing the date and a map of currency codes to exchange rate strings. Accepts optional target symbols and a base currency (defaults to USD). Returns a 400 error for invalid dates or range exceeded, and a 404 error when no data is available.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 3
---

## Table of Contents

- [Currency Time Series - Historical Currency Exchange Rates for a Time Interval v1.0.0](#currency-time-series-historical-currency-exchange-rates-for-a-time-interval-v100)
  - [Authentication](#authentication)
  - [Currency APIs](#currency-apis)
    - [getTimeSeries](#gettimeseries)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [CurrencyTimeseriesResponse](#currencytimeseriesresponse)
    - [CurrencyTimeSeriesItem](#currencytimeseriesitem)
    - [ErrorResponse](#errorresponse)



# Currency Time Series - Historical Currency Exchange Rates for a Time Interval v1.0.0

Retrieve day-by-day historical exchange rates for any base currency over a custom date range up to 1 year. Returns an array of daily rate objects, each containing the date and a map of currency codes to exchange rate strings. Accepts optional target symbols and a base currency (defaults to USD). Returns a 400 error for invalid dates or range exceeded, and a 404 error when no data is available.

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

### getTimeSeries

`GET /currency/time-series`

*Get time series of exchange rates*

Returns day-by-day historical exchange rates for a custom date range.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Response format: `json` (default) or `xml`.|
|startDate|query|string|true|Start date in `YYYY-MM-DD` format.|
|endDate|query|string|false|End date in `YYYY-MM-DD` format. Defaults to yesterday.|
|base|query|string|false|Base currency code. Defaults to `USD`.|
|symbols|query|string|false|Comma-separated currency codes. Omit to get all available rates.|

##### Enumerated Values

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

> Example responses

> Successful operation

```json
{
  "startDate": "2025-01-01",
  "endDate": "2025-01-07",
  "base": "USD",
  "historicalRatesList": [
    {
      "date": "2025-01-01",
      "rates": {
        "EUR": "0.96605",
        "PKR": "278.4"
      }
    },
    {
      "date": "2025-01-02",
      "rates": {
        "EUR": "0.9739",
        "PKR": "278.4"
      }
    },
    {
      "date": "2025-01-03",
      "rates": {
        "EUR": "0.97005",
        "PKR": "278.4"
      }
    },
    {
      "date": "2025-01-04",
      "rates": {
        "EUR": "0.97005",
        "PKR": "278.4"
      }
    },
    {
      "date": "2025-01-05",
      "rates": {
        "EUR": "0.9704",
        "PKR": "278.4"
      }
    },
    {
      "date": "2025-01-06",
      "rates": {
        "EUR": "0.96305",
        "PKR": "278.4"
      }
    },
    {
      "date": "2025-01-07",
      "rates": {
        "EUR": "0.967",
        "PKR": "278.4"
      }
    }
  ]
}
```

> Bad request - Invalid dates or range exceeded

```json
{
  "error": "Invalid Param Exception",
  "message": "please pass correct parameters",
  "path": "/v1.0/currency/time-series",
  "status": 400,
  "timestamp": "2026-07-27T12:08:01.002Z"
}
```

```json
{
  "timestamp": 1785154081486,
  "status": 400,
  "error": "Invalid Param Exception",
  "message": "You can only retrieve time series data for a maximum interval of 1 Year",
  "path": "/v2.0/timeseries"
}
```

```json
{
  "timestamp": 1785154082031,
  "status": 400,
  "error": "Invalid Param Exception",
  "message": "Starting date cannot be after current date or ending date.",
  "path": "/v2.0/timeseries"
}
```

```json
{
  "timestamp": 1785154106063,
  "status": 400,
  "error": "Invalid Param Exception",
  "message": "Provided Dates are in Invalid Format. Dates must be in a valid format YYYY-MM-DD!",
  "path": "/v2.0/timeseries"
}
```

> Not found - No data for interval

```json
{
  "timestamp": 1785154125982,
  "status": 404,
  "error": "Not Found Exception",
  "message": "Rates of provided base and symbols are not found for given intervals.",
  "path": "/v2.0/timeseries"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful operation|[CurrencyTimeseriesResponse](#currencytimeseriesresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad request - Invalid dates or range exceeded|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not found - No data for interval|[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

### CurrencyTimeseriesResponse

Currency time series response containing daily exchange rate data over a date range.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|startDate|string|true|none|Start date of the interval (YYYY-MM-DD).|
|endDate|string|true|none|End date of the interval (YYYY-MM-DD).|
|base|string|true|none|Base currency used for all rates in the series.|
|historicalRatesList|[[CurrencyTimeSeriesItem](#currencytimeseriesitem)]|true|none|Array of daily rate objects within the specified interval.|

### CurrencyTimeSeriesItem

Daily exchange rate data for a specific date.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|date|string|true|none|Date within the interval (YYYY-MM-DD).|
|rates|object|true|none|Map of currency codes to exchange rate strings for that 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 use a Unix millisecond timestamp and an internal service path instead.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|timestamp|string | integer|false|none|Timestamp when the error occurred — ISO 8601 string for gateway errors, Unix milliseconds integer for currency-service errors.|
|status|integer|false|none|HTTP status code returned with the error.|
|error|string|false|none|Specific error 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.|