# CSV Exports

## Generate a presigned S3 URL for a bulk export file

> Return a time-limited presigned URL for a bulk export object on S3.\
> \
> Caller supplies dataset id, date, and (optionally) file type; the server\
> constructs the S3 key per the layout documented in\
> \`gitbook/bulk-csv-download/folder-structure.md\`.

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/csv-exports/{dataset_id}/{export_date}":{"get":{"tags":["CSV Exports"],"summary":"Generate a presigned S3 URL for a bulk export file","description":"Return a time-limited presigned URL for a bulk export object on S3.\n\nCaller supplies dataset id, date, and (optionally) file type; the server\nconstructs the S3 key per the layout documented in\n`gitbook/bulk-csv-download/folder-structure.md`.","operationId":"get_export_presigned_url_v1_csv_exports__dataset_id___export_date__get","parameters":[{"name":"dataset_id","in":"path","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"export_date","in":"path","required":true,"schema":{"type":"string","format":"date","description":"ISO 8601 date of the partition, e.g. `2025-03-14`.","title":"Export Date"},"description":"ISO 8601 date of the partition, e.g. `2025-03-14`."},{"name":"file_type","in":"query","required":false,"schema":{"const":"csv","type":"string","description":"File format. Currently only `csv` (gzipped) is available.","default":"csv","title":"File Type"},"description":"File format. Currently only `csv` (gzipped) is available."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresignedUrlResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"PresignedUrlResponse":{"properties":{"presigned_url":{"type":"string","title":"Presigned Url","description":"Time-limited HTTPS URL to download the requested file."},"expires_in_seconds":{"type":"integer","title":"Expires In Seconds","description":"Number of seconds the presigned URL is valid for."},"bucket":{"type":"string","title":"Bucket","description":"S3 bucket the object lives in."},"object_key":{"type":"string","title":"Object Key","description":"S3 object key the URL points to."}},"type":"object","required":["presigned_url","expires_in_seconds","bucket","object_key"],"title":"PresignedUrlResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List available bulk export files for a dataset

> List the per-day export files available on S3 for a dataset.\
> \
> Each entry includes the partition date, object size, and last-modified\
> timestamp; combine with \`GET /{dataset\_id}/{date}\` to fetch a presigned\
> URL for any specific file.

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/csv-exports/{dataset_id}":{"get":{"tags":["CSV Exports"],"summary":"List available bulk export files for a dataset","description":"List the per-day export files available on S3 for a dataset.\n\nEach entry includes the partition date, object size, and last-modified\ntimestamp; combine with `GET /{dataset_id}/{date}` to fetch a presigned\nURL for any specific file.","operationId":"list_dataset_exports_v1_csv_exports__dataset_id__get","parameters":[{"name":"dataset_id","in":"path","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":9999,"minimum":1900},{"type":"null"}],"description":"Optional. Restrict the listing to a single year.","title":"Year"},"description":"Optional. Restrict the listing to a single year."},{"name":"month","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":12,"minimum":1},{"type":"null"}],"description":"Optional. Restrict the listing to a single month. Requires `year`.","title":"Month"},"description":"Optional. Restrict the listing to a single month. Requires `year`."},{"name":"file_type","in":"query","required":false,"schema":{"const":"csv","type":"string","description":"File format to list. Currently only `csv` (gzipped).","default":"csv","title":"File Type"},"description":"File format to list. Currently only `csv` (gzipped)."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetExportsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"DatasetExportsListResponse":{"properties":{"dataset_id":{"type":"string","title":"Dataset Id"},"file_type":{"type":"string","const":"csv","title":"File Type"},"count":{"type":"integer","title":"Count"},"files":{"items":{"$ref":"#/components/schemas/DatasetExportFile"},"type":"array","title":"Files"}},"type":"object","required":["dataset_id","file_type","count","files"],"title":"DatasetExportsListResponse"},"DatasetExportFile":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Partition date for this file."},"size_bytes":{"type":"integer","title":"Size Bytes","description":"Object size in bytes."},"last_modified":{"type":"string","format":"date-time","title":"Last Modified","description":"When the object was last written by the export pipeline."}},"type":"object","required":["date","size_bytes","last_modified"],"title":"DatasetExportFile"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gridstatus.io/developers/api-reference/csv-exports.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.