> ## Documentation Index > Fetch the complete documentation index at: https://docs.messari.io/llms.txt > Use this file to discover all available pages before exploring further. # Download Dataset > Downloads bulk timeseries data for a specific dataset at a given granularity. Data can be exported in CSV or JSONL format. The response includes all metric columns configured for bulk output. Time range is limited to prevent excessive data downloads. ## Overview Downloads bulk timeseries data for a specific dataset at the specified granularity. The data is streamed directly as a file in either CSV or JSONL format, making it ideal for large-scale data downloads. ## Path Parameters * **datasetSlug** (required): The slug identifier of the dataset to download. Use the [Get Available Datasets](/api-reference/endpoints/bulk/get-v1-datasets) endpoint to discover available dataset slugs. * **granularity** (required): The time interval for the data points. Available options: `1d`, `1w` ## Query Parameters * **rangeStart** (required): Start of the time range in ISO 8601 format (e.g., `2024-01-01T00:00:00Z`) * **rangeEnd** (required): End of the time range in ISO 8601 format (e.g., `2024-12-31T23:59:59Z`) * **format** (optional): Output format - either `csv` (default) or `jsonl` ## Output Formats ### CSV Format Comma-separated values with a header row. Compatible with Excel, Google Sheets, pandas, and most data analysis tools. ```csv theme={null} asset_id,timestamp,price_usd,market_cap_usd,volume_24h btc,2024-01-01T00:00:00Z,42500.50,834215000000,18234567890 eth,2024-01-01T00:00:00Z,2250.75,270500000000,8945123456 ``` ### JSONL Format JSON Lines format with one JSON object per line. Ideal for streaming processing and database imports. ```jsonl theme={null} {"asset_id":"btc","timestamp":"2024-01-01T00:00:00Z","price_usd":42500.50,"market_cap_usd":834215000000,"volume_24h":18234567890} {"asset_id":"eth","timestamp":"2024-01-01T00:00:00Z","price_usd":2250.75,"market_cap_usd":270500000000,"volume_24h":8945123456} ``` ## Time Range Limits To prevent excessive data downloads, time ranges are limited based on granularity: * **1d**: Maximum 365 days per request * **1w**: Maximum 1095 days (3 years) per request For larger time ranges, make multiple requests with different date ranges. ## Usage Examples ### Download CSV Data ```bash theme={null} curl -X GET "https://api.messari.io/bulk/v1/datasets/asset_price/1d/data?rangeStart=2024-01-01T00:00:00Z&rangeEnd=2024-12-31T23:59:59Z&format=csv" \ -H "x-messari-api-key: YOUR_API_KEY" \ -o asset_price_data.csv ``` ### Download JSONL Data ```bash theme={null} curl -X GET "https://api.messari.io/bulk/v1/datasets/asset_price/1h/data?rangeStart=2024-01-01T00:00:00Z&rangeEnd=2024-01-31T23:59:59Z&format=jsonl" \ -H "x-messari-api-key: YOUR_API_KEY" \ -o asset_price_data.jsonl ``` ### Python Example with pandas ```python theme={null} import pandas as pd import requests url = "https://api.messari.io/bulk/v1/datasets/asset_price/1d/data" params = { "rangeStart": "2024-01-01T00:00:00Z", "rangeEnd": "2024-12-31T23:59:59Z", "format": "csv" } headers = {"x-messari-api-key": "YOUR_API_KEY"} response = requests.get(url, params=params, headers=headers) df = pd.read_csv(pd.io.common.BytesIO(response.content)) print(df.head()) ``` ## Response Headers The response includes helpful headers: * **Content-Type**: `text/csv; charset=utf-8` or `application/x-ndjson` * **Content-Disposition**: Suggests a filename for the download (e.g., `asset_price_1d_2024-01-01_2024-12-31.csv`) * **Content-Encoding**: `gzip` if compression is applied ## Error Responses ### 400 Bad Request * Invalid date format * End date before start date * Time range exceeds maximum allowed for the granularity * Invalid format parameter ### 403 Forbidden * Your subscription tier does not have access to this dataset ### 404 Not Found * Dataset slug does not exist * Granularity not supported for this dataset ## Best Practices 1. **Start with the datasets catalog**: Always check available datasets first to see supported granularities 2. **Respect time range limits**: Break large downloads into smaller time windows 3. **Use appropriate granularity**: Choose the coarsest granularity that meets your needs to reduce data transfer 4. **Handle errors gracefully**: Implement retry logic for transient network errors 5. **Store data efficiently**: Consider using columnar formats like Parquet for long-term storage after download ## OpenAPI ````yaml GET /bulk/v1/datasets/{datasetSlug}/{granularity}/data openapi: 3.0.0 info: description: >- The Bulk API provides access to download large timeseries datasets in CSV or JSONL format. This API is optimized for downloading historical data at scale, supporting multiple granularities and dataset types. title: Messari API - Bulk V1 version: 1.0.0 servers: - description: Messari Bulk API url: https://api.messari.io security: - ApiKeyAuth: [] paths: /bulk/v1/datasets/{datasetSlug}/{granularity}/data: get: tags: - Bulk API description: >- Downloads bulk timeseries data for a specific dataset at a given granularity. Data can be exported in CSV or JSONL format. The response includes all metric columns configured for bulk output. Time range is limited to prevent excessive data downloads. operationId: DownloadBulkDatasetData parameters: - name: datasetSlug in: path required: true description: >- Dataset slug identifier. Use /bulk/v1/datasets to see all available datasets. schema: type: string enum: - asset-marketcap - asset-price - asset-supply - market default: asset-price - name: granularity in: path required: true description: Data granularity interval schema: type: string enum: - 1d - 1w default: 1d - name: rangeStart in: query required: true description: Start of time range in ISO 8601 format schema: type: string format: date-time default: '2025-10-01T00:00:00Z' example: '2025-10-01T00:00:00Z' - name: rangeEnd in: query required: true description: End of time range in ISO 8601 format schema: type: string format: date-time default: '2025-10-07T23:59:59Z' example: '2025-10-07T23:59:59Z' - name: format in: query required: false description: Output format for the data schema: type: string enum: - csv - jsonl default: csv responses: '200': description: Successfully generated and streaming bulk data file content: text/csv: schema: type: string format: binary example: | asset_id,timestamp,price_usd,market_cap_usd btc,2024-01-01T00:00:00Z,42500.50,834215000000 eth,2024-01-01T00:00:00Z,2250.75,270500000000 application/x-ndjson: schema: type: string format: binary example: > {"asset_id":"btc","timestamp":"2024-01-01T00:00:00Z","price_usd":42500.50,"market_cap_usd":834215000000} {"asset_id":"eth","timestamp":"2024-01-01T00:00:00Z","price_usd":2250.75,"market_cap_usd":270500000000} headers: Content-Disposition: description: Suggests filename for downloaded file schema: type: string example: attachment; filename=asset_price_1d_2024-01-01_2024-12-31.csv Content-Type: description: MIME type of the response schema: type: string example: text/csv; charset=utf-8 '400': description: Bad request - invalid parameters, time range, or format content: application/json: schema: properties: error: type: string type: object examples: invalidRange: value: error: >- invalid range: 2024-01-01T00:00:00Z to 2023-01-01T00:00:00Z invalidFormat: value: error: 'invalid format: xml' rangeExceeded: value: error: >- requested time range exceeds maximum allowed for this granularity '403': description: Forbidden - insufficient subscription tier for this dataset content: application/json: schema: properties: error: type: string type: object '404': description: Not found - dataset does not exist content: application/json: schema: properties: error: type: string type: object '500': description: Internal server error content: application/json: schema: properties: error: type: string type: object components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-messari-api-key description: >- API key for authentication. Get your key at https://messari.io/account/api ````