# Histdata — Zapi reference

> Which years exist for a pair, and in what unit each is served. HistData chunks

**Base URL:** `https://api.zpi.web.id`
**Auth:** Send `x-api-key: YOUR_KEY` header on every request. Get a free key at https://zpi.web.id/dashboard/keys.
**Response envelope:** `{ content, message, errors }`
**Rate limit:** 60 req/min on free tier.

**Related:**
- Detail page: https://zpi.web.id/api/finance/histdata
- Endpoint catalog: https://zpi.web.id/category/finance
- Concise index: https://zpi.web.id/llms.txt
- Full reference: https://zpi.web.id/llms-full.txt

---

## Histdata

**Category:** finance · **Slug:** `histdata`
**Detail page:** https://zpi.web.id/api/finance/histdata

Which years exist for a pair, and in what unit each is served. HistData chunks

**Tags:** finance, histdata

### Coverage

Which years exist for a pair, and in what unit each is served. HistData chunks

- **Method:** `GET`
- **Endpoint:** `https://api.zpi.web.id/v1/finance:histdata/coverage`
- **Cache TTL:** 86400s

**Parameters:**

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| `pair` | string | query | yes | Instrument code as HistData spells it, e.g. XAUUSD, EURUSD, SPXUSD. |
| `timeframe` | enum(m1|tick) | query | no | m1 (1-minute bars) or tick. Default m1. |

**cURL:**
```bash
curl "https://api.zpi.web.id/v1/finance:histdata/coverage?pair=XAUUSD&timeframe=m1" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zpi.web.id/v1/finance:histdata/coverage?pair=XAUUSD&timeframe=m1", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zpi.web.id/v1/finance:histdata/coverage?pair=XAUUSD&timeframe=m1",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

**Example response:**
```json
{
  "pair": "XAUUSD",
  "count": 18,
  "items": [
    {
      "unit": "month",
      "year": 2026,
      "months": [
        1,
        2,
        3,
        4,
        5,
        6,
        7,
        8
      ]
    },
    {
      "unit": "year",
      "year": 2025,
      "months": []
    },
    {
      "unit": "year",
      "year": 2024,
      "months": []
    },
    {
      "unit": "year",
      "year": 2023,
      "months": []
    },
    {
      "unit": "year",
      "year": 2022,
      "months": []
    },
    {
      "unit": "year",
      "year": 2021,
      "months": []
    },
    {
      "unit": "year",
      "year": 2020,
      "months": []
    },
    {
      "unit": "year",
      "year": 2019,
      "months": []
    }
  ],
  "dataset": "coverage",
  "lastYear": 2026,
  "provider": "histdata",
  "firstYear": 2009,
  "timeframe": "m1"
}
```

---

### Gap Report

HistData's own audit of where its data is missing, for one file. Cheap — it is

- **Method:** `GET`
- **Endpoint:** `https://api.zpi.web.id/v1/finance:histdata/gap-report`
- **Cache TTL:** 86400s

**Parameters:**

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| `pair` | string | query | yes | Instrument code as HistData spells it. |
| `year` | number | query | yes | Calendar year of the file. The current year has no report until it closes. |
| `month` | number | query | no | Month 1-12. Required for tick and for the current year; omit for a closed year of M1. |
| `timeframe` | enum(m1|tick) | query | no | m1 (1-minute bars) or tick. Default m1. |
| `sessionBreaks` | enum(include|exclude) | query | no | Whether to keep the daily 17:00-18:00 EST rollover gaps. Default exclude. |

**cURL:**
```bash
curl "https://api.zpi.web.id/v1/finance:histdata/gap-report?pair=XAUUSD&year=2024&month=7&timeframe=m1&sessionBreaks=exclude" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zpi.web.id/v1/finance:histdata/gap-report?pair=XAUUSD&year=2024&month=7&timeframe=m1&sessionBreaks=exclude", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zpi.web.id/v1/finance:histdata/gap-report?pair=XAUUSD&year=2024&month=7&timeframe=m1&sessionBreaks=exclude",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

**Example response:**
```json
{
  "file": "DAT_ASCII_XAUUSD_M1_2024.csv",
  "pair": "XAUUSD",
  "year": 2024,
  "count": 5,
  "items": [
    {
      "to": "2024-04-10T18:01:06-05:00",
      "from": "2024-04-10T16:59:59-05:00",
      "seconds": 3660,
      "sessionBreak": false
    },
    {
      "to": "2024-10-09T20:11:48-05:00",
      "from": "2024-10-09T19:05:51-05:00",
      "seconds": 3951,
      "sessionBreak": false
    },
    {
      "to": "2024-11-21T18:00:00-05:00",
      "from": "2024-11-21T16:59:34-05:00",
      "seconds": 3619,
      "sessionBreak": false
    },
    {
      "to": "2024-12-11T18:02:01-05:00",
      "from": "2024-12-11T16:59:59-05:00",
      "seconds": 3715,
      "sessionBreak": false
    },
    {
      "to": "2024-12-26T18:05:00-05:00",
      "from": "2024-12-26T16:59:59-05:00",
      "seconds": 3894,
      "sessionBreak": false
    }
  ],
  "month": null,
  "dataset": "gap-report",
  "provider": "histdata",
  "timezone": "EST-no-DST",
  "timeframe": "M1",
  "totalGaps": 313,
  "sessionBreaks": "exclude",
  "sessionBreakGaps": 308,
  "longestGapSeconds": 3951
}
```

---

### List Instruments

Every instrument HistData publishes, with the month its history starts.

- **Method:** `GET`
- **Endpoint:** `https://api.zpi.web.id/v1/finance:histdata/list-instruments`
- **Cache TTL:** 86400s

**Parameters:**

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| `timeframe` | enum(m1|tick) | query | no | Which index to read: m1 (1-minute bars) or tick. Default m1. |
| `query` | string | query | no | Filter by instrument code or display name, case-insensitive. |
| `page` | number | query | no | Page of instruments. Default 1. |
| `limit` | number | query | no | Instruments per page. Default 50, max 100. |

**cURL:**
```bash
curl "https://api.zpi.web.id/v1/finance:histdata/list-instruments?timeframe=m1&query=xau&page=1&limit=50" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zpi.web.id/v1/finance:histdata/list-instruments?timeframe=m1&query=xau&page=1&limit=50", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zpi.web.id/v1/finance:histdata/list-instruments?timeframe=m1&query=xau&page=1&limit=50",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

**Example response:**
```json
{
  "page": 1,
  "count": 50,
  "items": [
    {
      "name": "EUR/USD",
      "pair": "EURUSD",
      "startsAt": "2000-05",
      "startYear": 2000,
      "startMonth": 5
    },
    {
      "name": "EUR/CHF",
      "pair": "EURCHF",
      "startsAt": "2002-03",
      "startYear": 2002,
      "startMonth": 3
    },
    {
      "name": "EUR/GBP",
      "pair": "EURGBP",
      "startsAt": "2002-03",
      "startYear": 2002,
      "startMonth": 3
    },
    {
      "name": "EUR/JPY",
      "pair": "EURJPY",
      "startsAt": "2002-03",
      "startYear": 2002,
      "startMonth": 3
    },
    {
      "name": "EUR/AUD",
      "pair": "EURAUD",
      "startsAt": "2002-08",
      "startYear": 2002,
      "startMonth": 8
    },
    {
      "name": "USD/CAD",
      "pair": "USDCAD",
      "startsAt": "2000-06",
      "startYear": 2000,
      "startMonth": 6
    },
    {
      "name": "USD/CHF",
      "pair": "USDCHF",
      "startsAt": "2000-05",
      "startYear": 2000,
      "startMonth": 5
    },
    {
      "name": "USD/JPY",
      "pair": "USDJPY",
      "startsAt": "2000-05",
      "startYear": 2000,
      "startMonth": 5
    }
  ],
  "query": null,
  "total": 66,
  "dataset": "instruments",
  "hasMore": true,
  "nextPage": 2,
  "provider": "histdata",
  "timeframe": "m1"
}
```

---

### Download M1

One-minute OHLC bars from HistData — the fallback book behind `finance/dukascopy`

- **Method:** `GET`
- **Endpoint:** `https://api.zpi.web.id/v1/finance:histdata/download-m1`
- **Cache TTL:** 86400s

**Parameters:**

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| `pair` | string | query | yes | Instrument code as HistData spells it. XAUUSD starts 2009-03. |
| `year` | number | query | yes | Calendar year to download. |
| `month` | number | query | no | Month 1-12. Required for the current year, which ships month by month; narrows a closed year. |
| `page` | number | query | no | Page of bars. Default 1. |
| `limit` | number | query | no | Bars per page. Default 5000, max 20000. |

**cURL:**
```bash
curl "https://api.zpi.web.id/v1/finance:histdata/download-m1?pair=XAUUSD&year=2023&month=7&page=1&limit=5000" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zpi.web.id/v1/finance:histdata/download-m1?pair=XAUUSD&year=2023&month=7&page=1&limit=5000", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zpi.web.id/v1/finance:histdata/download-m1?pair=XAUUSD&year=2023&month=7&page=1&limit=5000",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

**Example response:**
```json
{
  "file": "DAT_ASCII_XAUUSD_M1_2023.csv",
  "page": 1,
  "pair": "XAUUSD",
  "unit": "year",
  "year": 2023,
  "count": 5000,
  "items": [
    {
      "low": 1826.617,
      "high": 1827.337,
      "open": 1826.837,
      "time": "2023-01-02T18:00:00-05:00",
      "close": 1826.637
    },
    {
      "low": 1826.137,
      "high": 1827.357,
      "open": 1826.537,
      "time": "2023-01-02T18:01:00-05:00",
      "close": 1826.537
    },
    {
      "low": 1826.137,
      "high": 1826.737,
      "open": 1826.137,
      "time": "2023-01-02T18:02:00-05:00",
      "close": 1826.737
    },
    {
      "low": 1827.187,
      "high": 1828.867,
      "open": 1827.187,
      "time": "2023-01-02T18:05:00-05:00",
      "close": 1828.738
    },
    {
      "low": 1828.758,
      "high": 1829.958,
      "open": 1828.758,
      "time": "2023-01-02T18:06:00-05:00",
      "close": 1829.497
    },
    {
      "low": 1828.117,
      "high": 1829.507,
      "open": 1829.497,
      "time": "2023-01-02T18:07:00-05:00",
      "close": 1829.397
    },
    {
      "low": 1828.718,
      "high": 1829.357,
      "open": 1829.357,
      "time": "2023-01-02T18:08:00-05:00",
      "close": 1829.277
    },
    {
      "low": 1828.757,
      "high": 1829.488,
      "open": 1829.277,
      "time": "2023-01-02T18:09:00-05:00",
      "close": 1829.298
    }
  ],
  "month": null,
  "total": 308812,
  "dataset": "m1",
  "hasMore": true,
  "nextPage": 2,
  "provider": "histdata",
  "timezone": "EST-no-DST",
  "priceSide": "bid",
  "timeframe": "M1"
}
```

---

### Download Tick

Tick quotes from HistData — bid AND ask, so a real spread per tick, which the

- **Method:** `GET`
- **Endpoint:** `https://api.zpi.web.id/v1/finance:histdata/download-tick`
- **Cache TTL:** 86400s

**Parameters:**

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| `pair` | string | query | yes | Instrument code as HistData spells it. XAUUSD starts 2009-03. |
| `date` | string | query | yes | One trading day, YYYY-MM-DD. A whole tick month is millions of rows and is never served at once. |
| `page` | number | query | no | Page of ticks. Default 1. |
| `limit` | number | query | no | Ticks per page. Default 5000, max 20000. |

**cURL:**
```bash
curl "https://api.zpi.web.id/v1/finance:histdata/download-tick?pair=XAUUSD&date=2026-07-15&page=1&limit=5000" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zpi.web.id/v1/finance:histdata/download-tick?pair=XAUUSD&date=2026-07-15&page=1&limit=5000", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zpi.web.id/v1/finance:histdata/download-tick?pair=XAUUSD&date=2026-07-15&page=1&limit=5000",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

**Example response:**
```json
{
  "date": "2026-07-15",
  "file": "DAT_ASCII_XAUUSD_T_202607.csv",
  "page": 1,
  "pair": "XAUUSD",
  "unit": "month",
  "count": 5000,
  "items": [
    {
      "ask": 4031.865,
      "bid": 4031.085,
      "time": "2026-07-15T00:00:00.000-05:00",
      "spread": 0.78
    },
    {
      "ask": 4031.865,
      "bid": 4031.065,
      "time": "2026-07-15T00:00:00.000-05:00",
      "spread": 0.8
    },
    {
      "ask": 4031.905,
      "bid": 4031.185,
      "time": "2026-07-15T00:00:00.000-05:00",
      "spread": 0.72
    },
    {
      "ask": 4031.905,
      "bid": 4031.145,
      "time": "2026-07-15T00:00:00.000-05:00",
      "spread": 0.76
    },
    {
      "ask": 4031.875,
      "bid": 4031.165,
      "time": "2026-07-15T00:00:00.000-05:00",
      "spread": 0.71
    },
    {
      "ask": 4031.875,
      "bid": 4031.105,
      "time": "2026-07-15T00:00:00.000-05:00",
      "spread": 0.77
    },
    {
      "ask": 4031.875,
      "bid": 4031.085,
      "time": "2026-07-15T00:00:00.000-05:00",
      "spread": 0.79
    },
    {
      "ask": 4031.745,
      "bid": 4030.945,
      "time": "2026-07-15T00:00:00.000-05:00",
      "spread": 0.8
    }
  ],
  "total": 379210,
  "dataset": "tick",
  "hasMore": true,
  "nextPage": 2,
  "provider": "histdata",
  "timezone": "EST-no-DST",
  "timeframe": "T"
}
```

---


_Generated: 2026-08-21T07:33:03.236Z_