> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powersignals.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# Grid Stress Index

> Returns the Grid Stress Index for the given time range. This is a derived signal computed from grid system state data, indicating overall grid stress level. Only 1h interval is supported.

## Overview

The Grid Stress Index is a derived signal that indicates the overall stress level of the South African power grid at any given hour. It is computed from multiple system state factors including residual demand, OCGT ramp rates, renewable penetration, and reserve margins.

### Interpretation

| Value Range | Meaning                                               |
| ----------- | ----------------------------------------------------- |
| 0.0 – 0.3   | Low stress — grid operating comfortably               |
| 0.3 – 0.6   | Moderate stress — elevated demand or reduced reserves |
| 0.6 – 0.8   | High stress — potential for loadshedding              |
| 0.8 – 1.0   | Critical — loadshedding likely or active              |

### Components

Each data point includes a `components` object breaking down the factors contributing to the stress score:

```json theme={null}
{
  "ts": "2026-01-01T18:00:00Z",
  "value": 0.72,
  "components": {
    "residual_demand": 0.8,
    "ocgt_ramp": 0.6,
    "reserve_margin": 0.75,
    "renewable_shortfall": 0.65
  },
  "version": "v1"
}
```

### Use Cases

* Trigger alerts when grid stress exceeds a threshold
* Correlate grid stress with market prices
* Power demand-response automation
* Feed into energy trading models


## OpenAPI

````yaml get /api/v1/features/grid-stress
openapi: 3.0.3
info:
  title: Power Signals API
  version: 1.0.0
  description: >-
    Clean, normalized, developer-ready datasets for energy traders, quants, and
    analysts.
  contact:
    email: support@powersignals.co.za
  license:
    name: Proprietary
servers:
  - url: https://api.powersignals.co.za
    description: Production
security: []
tags:
  - name: Generation
    description: Generation mix by fuel type (dispatchable + renewable)
  - name: Grid
    description: South African grid system state data
  - name: Features
    description: Derived analytical signals (Grid Stress Index, etc.)
paths:
  /api/v1/features/grid-stress:
    get:
      tags:
        - Features
      summary: Get grid stress index
      description: >-
        Returns the Grid Stress Index for the given time range. This is a
        derived signal computed from grid system state data, indicating overall
        grid stress level. Only 1h interval is supported.
      operationId: getGridStress
      parameters:
        - in: query
          name: components
          schema:
            type: boolean
          description: >-
            Include the components breakdown for each stress score. Defaults to
            false.
        - in: query
          name: end
          schema:
            type: string
          description: End datetime in ISO-8601 format.
          required: true
        - in: query
          name: interval
          schema:
            type: string
            enum:
              - 1h
          description: Data resolution. Only 1h is currently supported.
        - in: query
          name: start
          schema:
            type: string
          description: Start datetime in ISO-8601 format.
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GridStressResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    GridStressResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/GridStressMeta'
        data:
          type: array
          items:
            type: object
            additionalProperties: {}
      required:
        - data
        - meta
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        detail:
          type: string
      required:
        - detail
        - error
    GridStressMeta:
      type: object
      properties:
        dataset:
          type: string
          default: features.grid_stress_index
        feature:
          type: string
          default: grid_stress_index
        version:
          type: string
          default: v1
        interval:
          type: string
          default: 1h
        timezone:
          type: string
          default: UTC
        schema_version:
          type: string
          default: '1.0'
        derived:
          type: boolean
          default: true
        derivation_method:
          type: string
          default: computed_from_grid.system_state
        start:
          type: string
        end:
          type: string
      required:
        - end
        - start
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key obtained from the Power Signals dashboard.

````