Skip to main content

Making Your First Request

This guide walks through making your first API request to Snowtrail.

Fetching the Latest Signal​

Using the Python SDK​

from snowtrail import Snowtrail

client = Snowtrail(api_key="your-api-key")

# Fetch the latest system stress signal for US natural gas
df = client.gbsi_us.system_stress()
print(df[["signal_date", "stress_regime_label", "confidence_score"]])

Using the REST API​

curl "https://api.snowtrail.ai/gbsi_us/system_stress?latest=true" \
  -H "x-api-key: $SNOWTRAIL_API_KEY"

Fetching Historical Data​

Python SDK​

# Get historical system stress values for a date range
df = client.gbsi_us.system_stress(
    date_from="2024-01-01",
    date_to="2024-01-31"
)

print(df.head())

REST API​

curl "https://api.snowtrail.ai/gbsi_us/system_stress?date_from=2024-01-01&date_to=2024-01-31" \
  -H "x-api-key: $SNOWTRAIL_API_KEY"

Response Format​

Responses are returned in JSON format:

{
  "product_id": "gbsi_us",
  "count": 1,
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "signal_date": "2026-01-24",
      "stress_regime": 2,
      "stress_regime_label": "Balanced",
      "confidence_score": 0.82,
      "str_effective_at": "2026-01-24",
      "str_ingested_at": "2026-01-24T14:30:00Z"
    }
  ],
  "metadata": {
    "retrieved_at": "2026-01-24T15:00:00Z",
    "total_count": 1,
    "record_id": "req_abc123",
    "data_latest_date": "2026-01-24",
    "data_age_hours": 0.5
  }
}

Error Handling​

from snowtrail import Snowtrail, NotFoundError, AuthenticationError, RateLimitError

client = Snowtrail(api_key="your-api-key")

try:
    df = client.gbsi_us.system_stress()
except NotFoundError:
    print("Product or dataset not found")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded - SDK will automatically retry with exponential backoff")