Rate Limits

Understand API rate limits and how to handle throttling.

Rate Limits

The Power Signals API applies rate limiting per API key to ensure fair usage and service stability.

Limits by Scope

Scope	Endpoints	Limit
normalized_data	/grid/system-state	10 requests/min
features	/features/grid-stress	3 requests/min

Limits are applied on a rolling 60-second window per API key.

Rate Limit Response

When you exceed the limit, you’ll receive a 429 Too Many Requests response:

{
  "detail": "Request was throttled. Expected available in 42 seconds."
}

The response includes a Retry-After header indicating how many seconds to wait before retrying.

Best Practices

Cache Responses

Grid system state data is published hourly. There’s no benefit in requesting the same time range more than once per hour.

import requests
from functools import lru_cache
from datetime import datetime, timedelta

@lru_cache(maxsize=128)
def get_grid_state(start: str, end: str, interval: str = "1h"):
    response = requests.get(
        "https://api.powersignals.co.za/api/v1/grid/system-state",
        headers={"X-API-KEY": "your_api_key_here"},
        params={"start": start, "end": end, "interval": interval},
    )
    response.raise_for_status()
    return response.json()

Use Exponential Backoff

If you receive a 429, implement exponential backoff:

import time
import requests

def request_with_backoff(url, headers, params, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers, params=params)
        if response.status_code == 429:
            wait = 2 ** attempt
            time.sleep(wait)
            continue
        return response
    raise Exception("Max retries exceeded")

Request Larger Time Ranges

Instead of making many small requests, request larger time ranges in a single call. The API supports up to multi-day ranges.

# Instead of 24 separate hourly requests:
curl "https://api.powersignals.co.za/api/v1/grid/system-state?start=2026-01-01T00:00:00Z&end=2026-01-02T00:00:00Z&interval=1h" \
  -H "X-API-KEY: your_key"

Use Daily Aggregation

If you don’t need hourly granularity, use interval=1d to get daily summaries with fewer data points:

curl "https://api.powersignals.co.za/api/v1/grid/system-state?start=2026-01-01T00:00:00Z&end=2026-02-01T00:00:00Z&interval=1d" \
  -H "X-API-KEY: your_key"

Need Higher Limits?

Contact us at [e-mail] to discuss enterprise rate limits for high-volume use cases.