> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotizave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Historical rates

> Query a date or historical series within your plan’s retention window.

`GET /v1/fx/rates/:market/history`

<span id="request" />

## Request

| Parameter | Behaviour |
| - | - |
| `date` | `YYYY-MM-DD`, not in the future. Selects a point response and takes precedence over the range. |
| `from`, `to` | Inclusive UTC date range, `YYYY-MM-DD`. Without a range, uses the plan window. A future `to` is capped at today. |
| `granularity` | `daily` (default) or `raw`; for collections only. |
| `format` | [Response format](/en/api/formats). |

Run these examples on your server. JavaScript and Python use the clients in the [quickstart](/en/api/quickstart#paso-2); configure `COTIZAVE_API_KEY` there.

<CodeGroup>
  ```bash curl theme={null}
  curl --fail-with-body --max-time 10 "https://api.cotizave.com/v1/fx/rates/reference/history?granularity=daily" \
    -H "X-API-Key: $COTIZAVE_API_KEY"
  ```

  ```javascript Node.js theme={null}
  import { cotizave } from './cotizave.mjs';

  const data = await cotizave('/v1/fx/rates/reference/history?granularity=daily');
  console.log(data);
  ```

  ```python Python theme={null}
  from cotizave import cotizave

  data = cotizave('/v1/fx/rates/reference/history?granularity=daily')
  print(data)
  ```
</CodeGroup>

<span id="response" />

## Two response shapes

**With `date`**, returns the last record captured before the end of that UTC day. The capture may be from an earlier day if that day has no data. `date` is the requested date; check `captured_at` and `updated_at`.

Illustrative response: figures and dates are not current quotes.

```json theme={null}
{
  "market": "reference",
  "date": "2026-10-18",
  "rate": 475.0083,
  "updated_at": "2026-10-16T04:00:00Z",
  "captured_at": "2026-10-18T23:50:00Z"
}
```

**Without `date`**, returns an object with `points`, including when `from` and `to` are omitted; not a top-level array. Example collection with two points:

Illustrative response: figures and dates are not current quotes.

```json theme={null}
{
  "market": "reference",
  "from": "2026-10-17",
  "to": "2026-10-18",
  "granularity": "daily",
  "count": 2,
  "points": [
    {
      "date": "2026-10-17",
      "rate": 475.0083,
      "updated_at": "2026-10-16T04:00:00Z",
      "captured_at": "2026-10-17T23:50:00Z"
    },
    {
      "date": "2026-10-18",
      "rate": 475.0083,
      "updated_at": "2026-10-16T04:00:00Z",
      "captured_at": "2026-10-18T23:50:00Z"
    }
  ]
}
```

<span id="comportamiento" />

## Granularity and retention

`daily` returns the last available capture for each UTC day. `raw` returns individual captures, up to 5,000: if truncated, it keeps the most recent ones, orders them chronologically, adjusts `from` and adds `truncated: true`. Do not fill gaps as though they were new observations.

| Plan | Accessible retention in days |
| - | - |
| Gratis | 7 |
| Inicio | 30 |
| Esencial | 90 |
| Profesional | 180 |
| Escala | 365 |

Plan retention does not guarantee every market has data for that entire period. Series start dates and source interruptions limit actual coverage. Market access restrictions also apply.

<span id="errores" />

## Errors

`400` for invalid dates, range, granularity or parameters. `403 history_out_of_retention` includes `details.max_days`; `402 feature_not_in_plan` applies to a restricted market. `404` when no point record is available. A collection may have `count: 0` and `points: []`.

The [common errors](/en/api/errors) for authentication, quota and availability also apply. API error responses are JSON; branch on `code`, not on the text of `message`.

<span id="casos-uso" />

## Charts and reconciliation

Use `captured_at` as the observation time and `updated_at` as the source timestamp. Units depend on the market: `eur_reference` is VES/EUR; USD markets are VES/USD. Do not mix these units in a chart.

<span id="notas" />

## Dates and records

History groups captures by UTC, not by local dates in Australia, Argentina or Venezuela. A nearby capture does not establish the value date required for an invoice, and history does not return `effective_date`. Save that date and rate when issuing the record; do not reconstruct them by assuming `date` means value date.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.