openapi: 3.0.3
info:
  title: Grid Status API Info Query Data 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: Query Data
  description: Query dataset rows with filters, resampling, and pagination.
paths:
  /datasets/{dataset_id}/query:
    get:
      operationId: queryDataset
      tags:
      - Query Data
      summary: Query a dataset
      description: Query a dataset and return matching rows as JSON or CSV. Example dataset IDs include ercot_spp_day_ahead_hourly (ERCOT day-ahead settlement point prices), ercot_fuel_mix, ercot_as_prices, caiso_load, caiso_lmp_real_time_5_min, and pjm_lmp_real_time_5_min. Pass the X-Stream true request header to stream JSON rows from a server-side cursor instead of buffering the whole result (JSON only); in streaming mode read pagination from the JSON meta.hasNextPage and meta.cursor fields.
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      - name: start_time
        in: query
        description: Start of the time range filter on the dataset's time index column (ISO 8601). Rows on or after this time are returned.
        schema:
          type: string
      - name: end_time
        in: query
        description: End of the time range filter on the dataset's time index column (ISO 8601). Rows before this time are returned.
        schema:
          type: string
      - name: time
        in: query
        description: Point-in-time filter. Accepts 'latest' or an ISO 8601 timestamp. Cannot be combined with start_time or end_time.
        schema:
          type: string
      - name: time_comparison
        in: query
        description: Comparison operator used when filtering by time.
        schema:
          type: string
          enum:
          - '='
          - '>'
          - '>='
          - <
          - <=
      - name: publish_time
        in: query
        description: Filter based on the dataset's publish time column.
        schema:
          type: string
      - name: publish_time_start
        in: query
        description: Start of a publish-time range filter.
        schema:
          type: string
      - name: publish_time_end
        in: query
        description: End of a publish-time range filter.
        schema:
          type: string
      - name: filter_column
        in: query
        description: The column to filter results by (for example location).
        schema:
          type: string
      - name: filter_value
        in: query
        description: The value to filter results by.
        schema:
          type: string
      - name: filter_operator
        in: query
        description: Operator applied between filter_column and filter_value.
        schema:
          type: string
          enum:
          - '='
          - '!='
          - '>'
          - '>='
          - <
          - <=
          - in
          default: '='
      - name: columns
        in: query
        description: Comma separated list of columns to return. Defaults to all columns.
        schema:
          type: string
      - name: order
        in: query
        description: Sort order of results.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: limit
        in: query
        description: Maximum number of rows to return across all pages.
        schema:
          type: integer
      - name: page
        in: query
        description: Page number of results to return.
        schema:
          type: integer
          default: 1
      - name: page_size
        in: query
        description: Maximum number of rows to return in a single page.
        schema:
          type: integer
      - name: cursor
        in: query
        description: Cursor for cursor-based pagination.
        schema:
          type: string
      - name: timezone
        in: query
        description: Timezone used when interpreting timezone-naive timestamps and when resampling to frequencies of one day or longer.
        schema:
          type: string
      - name: resample_frequency
        in: query
        description: Frequency to resample the data to, from '1 minute' through '1 year' (for example '5 minutes', '1 hour', '1 day', '1 month').
        schema:
          type: string
      - name: resample_by
        in: query
        description: Comma separated list of columns to group by before resampling.
        schema:
          type: string
      - name: resample_function
        in: query
        description: Aggregation function used when resampling.
        schema:
          type: string
          enum:
          - mean
          - sum
          - min
          - max
          - count
          - stddev
          - variance
          default: mean
      - $ref: '#/components/parameters/ReturnFormat'
      - name: json_schema
        in: query
        description: Shape of the JSON response.
        schema:
          type: string
          enum:
          - array-of-objects
          - array-of-arrays
          default: array-of-objects
      - name: download
        in: query
        description: Whether to return the result as a file download.
        schema:
          type: boolean
          default: false
      - name: X-Stream
        in: header
        description: Set to true to stream JSON rows from a server-side cursor.
        schema:
          type: boolean
      responses:
        '200':
          description: Matching rows plus pagination and dataset metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryDatasetResponse'
            text/csv:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /datasets/{dataset_id}/query/{filter_column_id}/{filter_value_path}:
    get:
      operationId: queryDatasetByColumnValue
      tags:
      - Query Data
      summary: Query a dataset by column value
      description: Shortcut form of the query endpoint that filters by a single column value in the path (for example a location or settlement point). Accepts the same time-range, resampling, pagination, and format query parameters as the main query endpoint.
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      - name: filter_column_id
        in: path
        required: true
        description: The column to filter by.
        schema:
          type: string
      - name: filter_value_path
        in: path
        required: true
        description: The value to filter the column by.
        schema:
          type: string
      - $ref: '#/components/parameters/ReturnFormat'
      responses:
        '200':
          description: Matching rows plus pagination and dataset metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryDatasetResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    TooManyRequests:
      description: Rate limit exceeded for your plan.
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: Missing API Key.
    ValidationError:
      description: Validation error on request parameters.
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: array
                items:
                  type: object
  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:
    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
    QueryDatasetResponse:
      type: object
      properties:
        status_code:
          type: integer
        data:
          type: array
          description: Matching rows (array of objects by default).
          items:
            type: object
        meta:
          type: object
          properties:
            page:
              type: integer
            pageSize:
              type: integer
            hasNextPage:
              type: boolean
            cursor:
              type: string
              nullable: true
        dataset_metadata:
          $ref: '#/components/schemas/DatasetResponse'
  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).