openapi: 3.0.3
info:
  title: Grid Status API Info CSV Exports API
  description: The Grid Status hosted API provides programmatic access to United States and Canadian electricity grid and power market data across CAISO, ERCOT, IESO, ISONE, MISO, NYISO, PJM, and SPP. Data is organized as datasets - day-ahead and real-time LMP and settlement point prices, load and load forecasts, fuel mix, ancillary services, storage, and transmission constraints - that are listed, described, and queried through a uniform interface with time-range filters, column filters, resampling, pagination, and JSON or CSV output. Authenticate with an API key from the Grid Status settings page, passed in the x-api-key header (or api_key query parameter). Grounded in the live OpenAPI 3.1 document published at https://api.gridstatus.io/openapi.json (version 1.3.0).
  version: 1.3.0
  contact:
    name: Grid Status
    url: https://www.gridstatus.io
    email: contact@gridstatus.io
servers:
- url: https://api.gridstatus.io/v1
  description: Grid Status hosted API
security:
- apiKeyHeader: []
- apiKeyQuery: []
tags:
- name: CSV Exports
  description: Bulk per-day CSV export files on S3.
paths:
  /csv-exports/{dataset_id}:
    get:
      operationId: listCsvExports
      tags:
      - CSV Exports
      summary: List available bulk export files for a dataset
      description: List the per-day CSV export files available on S3 for a dataset. Each entry includes the partition date, object size, and last-modified timestamp.
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      responses:
        '200':
          description: Available bulk export files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetExportsListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /csv-exports/{dataset_id}/{export_date}:
    get:
      operationId: getCsvExportUrl
      tags:
      - CSV Exports
      summary: Generate a presigned S3 URL for a bulk export file
      description: Generate a presigned S3 URL to download a specific per-day export file.
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      - name: export_date
        in: path
        required: true
        description: The partition date of the export file (ISO 8601 date).
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Presigned URL for the export file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresignedUrlResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: The requested resource was not found.
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: Missing API Key.
  schemas:
    PresignedUrlResponse:
      type: object
      properties:
        url:
          type: string
          description: Presigned S3 URL for downloading the export file.
    DatasetExportsListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              size_bytes:
                type: integer
              last_modified_utc:
                type: string
                format: date-time
  parameters:
    DatasetId:
      name: dataset_id
      in: path
      required: true
      description: ID of the dataset (for example ercot_spp_day_ahead_hourly).
      schema:
        type: string
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key from https://www.gridstatus.io/settings/api.
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key passed as a query parameter (alternative to the header).