CSV Exports

Generate a presigned S3 URL for a bulk export file

get

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.

Path parameters

dataset_idstringRequired

export_datestring · dateRequired

ISO 8601 date of the partition, e.g. 2025-03-14.

Query parameters

file_typeconst: csvOptional

File format. Currently only csv (gzipped) is available.

Default: csv

api_keystring · nullableOptional

API key for authentication (query)

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

presigned_urlstringRequired

Time-limited HTTPS URL to download the requested file.

expires_in_secondsintegerRequired

Number of seconds the presigned URL is valid for.

bucketstringRequired

S3 bucket the object lives in.

object_keystringRequired

S3 object key the URL points to.

422

Validation Error

application/json

get/csv-exports/{dataset_id}/{export_date}

GET /v1/csv-exports/{dataset_id}/{export_date} HTTP/1.1
Host: api.gridstatus.io
Accept: */*

{
  "presigned_url": "text",
  "expires_in_seconds": 1,
  "bucket": "text",
  "object_key": "text"
}

List available bulk export files for a dataset

get

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.

Path parameters

dataset_idstringRequired

Query parameters

yearinteger · min: 1900 · max: 9999 · nullableOptional

Optional. Restrict the listing to a single year.

monthinteger · min: 1 · max: 12 · nullableOptional

Optional. Restrict the listing to a single month. Requires year.

file_typeconst: csvOptional

File format to list. Currently only csv (gzipped).

Default: csv

api_keystring · nullableOptional

API key for authentication (query)

Header parameters

x-api-keystring · nullableOptional

API key for authentication (header)

Responses

200

Successful Response

application/json

dataset_idstringRequired

file_typeconst: csvRequired

countintegerRequired

422

Validation Error

application/json

get/csv-exports/{dataset_id}

GET /v1/csv-exports/{dataset_id} HTTP/1.1
Host: api.gridstatus.io
Accept: */*

{
  "dataset_id": "text",
  "file_type": "text",
  "count": 1,
  "files": [
    {
      "date": "2026-01-01",
      "size_bytes": 1,
      "last_modified": "2026-01-01T00:00:00.000Z"
    }
  ]
}