Sustainability Time Series API

Get time series data for carbon and energy consumption.

GET /v1/sustainability/time-series

Overview

Returns carbon and energy data points aggregated by the specified interval (hour, day, week, or month). Use this endpoint for charts and trend analysis.

Request

cURL

curl "https://api.gateflow.ai/v1/sustainability/time-series?time_range=last_30_days&interval=day" \
  -H "Authorization: Bearer gw_prod_..."

Python

import requests

response = requests.get(
    "https://api.gateflow.ai/v1/sustainability/time-series",
    headers={"Authorization": "Bearer gw_prod_..."},
    params={
        "time_range": "last_30_days",
        "interval": "day"
    }
)

Parameters

Parameter	Type	Required	Default	Description
start_date	date	No	-	Start date (YYYY-MM-DD)
end_date	date	No	-	End date (YYYY-MM-DD)
time_range	string	No	last_7_days	Preset time range
interval	string	No	day	Aggregation: hour, day, week, month
project_id	string	No	null	Filter by project
team_id	string	No	null	Filter by team

Response

{
  "data_points": [
    {
      "timestamp": "2024-01-01T00:00:00Z",
      "carbon_gco2e": 180.5,
      "energy_kwh": 0.36,
      "requests": 2150,
      "tokens": 4500000,
      "avg_carbon_per_request": 0.084,
      "cache_hit_rate": 0.25
    },
    {
      "timestamp": "2024-01-02T00:00:00Z",
      "carbon_gco2e": 175.2,
      "energy_kwh": 0.35,
      "requests": 2100,
      "tokens": 4200000,
      "avg_carbon_per_request": 0.083,
      "cache_hit_rate": 0.28
    }
  ],
  "interval": "day",
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-01-30"
  }
}

Data Point Fields

Field	Type	Description
timestamp	string	ISO 8601 timestamp
carbon_gco2e	number	Carbon emissions in grams CO₂e
energy_kwh	number	Energy consumption in kWh
requests	integer	Number of requests
tokens	integer	Total tokens processed
avg_carbon_per_request	number	Average carbon per request
cache_hit_rate	number	Cache hit percentage (0-1)

Interval Options

Interval	Max Time Range	Use Case
hour	7 days	Real-time monitoring
day	90 days	Daily trends
week	1 year	Weekly reports
month	2 years	Long-term analysis

See Also

• Dashboard API - All metrics in one call
• Summary API - Aggregated KPIs