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

# Histórico de tasas

> Consulta una fecha o una serie histórica dentro de la retención de tu plan.

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

<span id="request" />

## Consulta

| Parámetro | Comportamiento |
| - | - |
| `date` | `YYYY-MM-DD`, no futura. Selecciona una respuesta puntual y tiene prioridad sobre el rango. |
| `from`, `to` | Rango inclusivo de fechas UTC, `YYYY-MM-DD`. Sin rango se usa la ventana del plan. Un `to` futuro se limita a hoy. |
| `granularity` | `daily` (por defecto) o `raw`; solo para colecciones. |
| `format` | [Formato de respuesta](/api/formats). |

Los ejemplos se ejecutan en el servidor. JavaScript y Python usan los clientes del [inicio rápido](/api/quickstart#paso-2); configura allí `COTIZAVE_API_KEY`.

<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" />

## Dos formas de respuesta

**Con `date`**, se devuelve el último registro capturado antes de terminar ese día UTC. Puede corresponder a una captura anterior si ese día no tiene datos. `date` es la fecha solicitada; comprueba `captured_at` y `updated_at`.

Respuesta ilustrativa: las cifras y fechas no son cotizaciones actuales.

```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"
}
```

**Sin `date`**, devuelve un objeto con `points`, incluso sin `from` y `to`; no un array en la raíz. Ejemplo de una colección con dos puntos:

Respuesta ilustrativa: las cifras y fechas no son cotizaciones actuales.

```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" />

## Granularidad y retención

`daily` devuelve la última captura disponible de cada día UTC. `raw` devuelve capturas individuales, con un máximo de 5.000: si se recorta, conserva las más recientes, las ordena cronológicamente, ajusta `from` y añade `truncated: true`. No rellenes huecos como si fueran observaciones nuevas.

| Plan | Días de retención accesibles |
| - | - |
| Gratis | 7 |
| Inicio | 30 |
| Esencial | 90 |
| Profesional | 180 |
| Escala | 365 |

La retención del plan no garantiza que cada mercado tenga datos para todo ese período. El inicio de cada serie y las interrupciones de la fuente limitan la cobertura efectiva. También se aplica el acceso por mercado.

<span id="errores" />

## Errores

`400` para fechas, rango, granularidad o parámetros inválidos. `403 history_out_of_retention` incluye `details.max_days`; `402 feature_not_in_plan` para un mercado restringido. `404` cuando no hay registro puntual disponible. Una colección puede tener `count: 0` y `points: []`.

Además pueden producirse los [errores comunes](/api/errors) de autenticación, cuota o disponibilidad. Las respuestas de error de la API son JSON; decide por `code`, no por el texto de `message`.

<span id="casos-uso" />

## Gráficas y conciliación

Usa `captured_at` como instante de observación y `updated_at` como fecha de la fuente. La unidad depende del mercado: `eur_reference` es VES/EUR; los mercados USD son VES/USD. Para graficar no mezcles ambas unidades.

<span id="notas" />

## Fechas y documentos

El histórico agrupa por captura UTC, no por la fecha local de Australia, Argentina o Venezuela. Una captura cercana no acredita la fecha valor requerida para una factura y el histórico no devuelve `effective_date`. Conserva esa fecha y la tasa al emitir el documento; no las reconstruyas suponiendo que `date` significa fecha valor.


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