openapi: 3.0.3
info:
  title: Grid Status API Info Dataset Metadata 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: Dataset Metadata
  description: List datasets and fetch per-dataset metadata.
paths:
  /datasets:
    get:
      operationId: listDatasets
      tags:
      - Dataset Metadata
      summary: List datasets
      description: List all published datasets the authenticated user has access to. The full catalog is browsable at https://www.gridstatus.io/datasets.
      parameters:
      - $ref: '#/components/parameters/ReturnFormat'
      responses:
        '200':
          description: A list of datasets with metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDatasetsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /datasets/{dataset_id}:
    get:
      operationId: getDatasetMetadata
      tags:
      - Dataset Metadata
      summary: Get dataset metadata
      description: Fetch metadata for a single dataset - description, earliest and latest available time, columns, primary key columns, time index column, source URL, approximate row count, data frequency, and publication frequency.
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      responses:
        '200':
          description: Dataset metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetResponse'
        '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.
  parameters:
    ReturnFormat:
      name: return_format
      in: query
      description: The return format of the response.
      schema:
        type: string
        enum:
        - json
        - csv
        default: json
    DatasetId:
      name: dataset_id
      in: path
      required: true
      description: ID of the dataset (for example ercot_spp_day_ahead_hourly).
      schema:
        type: string
  schemas:
    ListDatasetsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DatasetResponse'
    DatasetResponse:
      type: object
      properties:
        id:
          type: string
          example: ercot_spp_day_ahead_hourly
        name:
          type: string
        description:
          type: string
        earliest_available_time_utc:
          type: string
          format: date-time
        latest_available_time_utc:
          type: string
          format: date-time
        source:
          type: string
        source_url:
          type: string
        last_checked_time_utc:
          type: string
          format: date-time
        primary_key_columns:
          type: array
          items:
            type: string
        publish_time_column:
          type: string
          nullable: true
        time_index_column:
          type: string
        subseries_index_column:
          type: string
          nullable: true
        all_columns:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
              description:
                type: string
        number_of_rows_approximate:
          type: integer
        table_type:
          type: string
        data_frequency:
          type: string
        publication_frequency:
          type: string
        is_published:
          type: boolean
        status:
          type: string
        popularity_rank:
          type: integer
  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).