> ## 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.

# 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:

```json theme={null}
{
  "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.

```python theme={null}
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:

```python theme={null}
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.

```bash theme={null}
# 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:

```bash theme={null}
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 [support@powersignals.co.za](mailto:support@powersignals.co.za) to discuss enterprise rate limits for high-volume use cases.