# List of Downloadable Files (/bulk/list)

`GET`    /v2/bulk/list

## Overview

You can retrieve a list of files available for download in CSV format.\
You can get a list of files for a specific dataset by specifying an endpoint, or get a list of files across all accessible datasets for a specific date.\
You can use the obtained file list to download files with the [Get File Download URL API](/en/spec/bulk-get).

> **Note**
>
> For information on decompression methods and restrictions for CSV files obtained via Bulk API, please see [File Download](/en/spec/bulk).

### Attention

> **Info**
>
> - Files are compressed in gzip format.
> - File names include year and month information.
> - Either `endpoint` or `date` is required.

## Retrieve list of downloadable files

`GET` `https://api.jquants.com/v2/bulk/list`

In your request message, either "endpoint" or "date" must be specified.

### Parameter and Response

In your request message, either "endpoint" or "date" must be specified.\
Combination of parameter in the request and results are as below.

- endpoint: ✓, date: –, from /to: – → File list for the specified endpoint for the plan's full allowed period

- endpoint: ✓, date: –, from /to: ✓ → File list for the specified endpoint within the specified period

- endpoint: –, date: ✓, from /to: – → File list for the specified date across all accessible endpoints under your subscription

### Requests

### Headers

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| x-api-key | string | Required | API Key     |

### Query Parameters

> **Note**
>
> Either **endpoint** or **date** is required.

| Parameter | Type   | Required | Description                                                                                                                                         |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| endpoint  | string | Optional | Endpoint name of the data to retrieve (e.g. /equities/bars/daily). For a list of available values, please see [here](/en/spec/bulk-list/endpoints). |
| date      | string | Optional | Target date (YYYY-MM, YYYYMM, YYYY-MM-DD, or YYYYMMDD).                                                                                             |
| from      | string | Optional | Start date of the retrieval period (YYYY-MM, YYYYMM, YYYY-MM-DD, or YYYYMMDD). Only available when `endpoint` is specified.                         |
| to        | string | Optional | End date of the retrieval period (YYYY-MM, YYYYMM, YYYY-MM-DD, or YYYYMMDD). Only available when `endpoint` is specified.                           |

> **Info**
>
> - When only `endpoint` is specified, all files within the plan's allowed period are returned. You can narrow the period using `from`/`to`.
> - When only `date` is specified, files for that date from all endpoints accessible under your subscription are returned.
> - When Trading Calendar (/markets/calendar) is specified as the `endpoint`, only the latest file will be returned, regardless of the `from`/`to` period. Additionally, Trading Calendar cannot be retrieved with a `date` specification.

### Sample Code

/v2/bulk/list

**cURL**

```bash
curl -G https://api.jquants.com/v2/bulk/list \
-H "x-api-key: {{apiKey}}" \
-d endpoint="{{endpoint}}"
```

**JavaScript**

```javascript
import axios from 'axios'

const client = axios.create({
baseURL: "https://api.jquants.com",
headers: { "x-api-key": "{{apiKey}}" },
})

await client.get("/v2/bulk/list", {
params: {
  endpoint: "{{endpoint}}",
},
})
```

**Python**

```python
import requests

headers = {"x-api-key": "{{apiKey}}"}
resp = requests.get(
  "https://api.jquants.com/v2/bulk/list",
  params={"endpoint": "{{endpoint}}"},
  headers=headers,
)
print(resp.json())
```

### Responses

### Data Item

| Parameter    | Type   | Required | Description                                   |
| ------------ | ------ | -------- | --------------------------------------------- |
| Key          | string | Required | File key (used when downloading file)         |
| LastModified | string | Required | Last modified date and time (ISO 8601 format) |
| Size         | number | Required | File size (bytes)                             |

### Response Sample

```bash {{ title: "200:OK" }}
{
    "data": [
        {
            "Key": "equities/bars/daily/historical/2025/equities_bars_daily_202501.csv.gz",
            "LastModified": "2025-11-07T20:48:51.295000+00:00",
            "Size": 6933528
        },
        {
            "Key": "equities/bars/daily/historical/2024/equities_bars_daily_202412.csv.gz",
            "LastModified": "2025-01-07T18:30:15.123000+00:00",
            "Size": 6845123
        }
    ]
}
```