Optimization Opportunities API

Get actionable recommendations to reduce carbon footprint.

GET /v1/sustainability/optimization-opportunities

Overview

Analyzes your usage patterns and returns specific, actionable opportunities to reduce carbon emissions. Each opportunity includes potential savings and implementation guidance.

Request

cURL

curl "https://api.gateflow.ai/v1/sustainability/optimization-opportunities?days=30" \
  -H "Authorization: Bearer gw_prod_..."

Python

import requests

response = requests.get(
    "https://api.gateflow.ai/v1/sustainability/optimization-opportunities",
    headers={"Authorization": "Bearer gw_prod_..."},
    params={
        "days": 30,
        "project_id": "proj_abc123"
    }
)

Parameters

Parameter	Type	Required	Default	Description
days	integer	No	7	Days of history to analyze (1-90)
project_id	string	No	null	Filter by project
team_id	string	No	null	Filter by team

Response

{
  "opportunities": [
    {
      "id": "opt_001",
      "type": "model_downgrade",
      "priority": "high",
      "title": "Use smaller models for simple Q&A",
      "description": "18% of your requests use GPT-4o for simple question-answering tasks that could be handled by GPT-4o-mini with equivalent quality.",
      "affected_requests_percent": 18.5,
      "potential_savings_kg_co2": 2.8,
      "potential_savings_percent": 15.2,
      "implementation": {
        "action": "Enable intelligent routing",
        "code_change": "Set model='auto' instead of model='gpt-4o'",
        "dashboard_path": "/settings/routing",
        "api_endpoint": "PATCH /v1/settings/routing"
      },
      "impact": {
        "quality_impact": "none",
        "latency_impact": "improved",
        "cost_impact": "reduced"
      }
    },
    {
      "id": "opt_002",
      "type": "enable_caching",
      "priority": "high",
      "title": "Enable semantic caching",
      "description": "Detected 28% semantically similar queries that could be served from cache, eliminating redundant inference.",
      "affected_requests_percent": 28.0,
      "potential_savings_kg_co2": 3.2,
      "potential_savings_percent": 17.5,
      "implementation": {
        "action": "Enable caching in project settings",
        "dashboard_path": "/settings/caching",
        "api_endpoint": "PATCH /v1/settings/caching"
      }
    },
    {
      "id": "opt_003",
      "type": "green_routing",
      "priority": "medium",
      "title": "Route to low-carbon regions",
      "description": "During peak hours (14:00-18:00 UTC), route non-latency-sensitive requests to providers with cleaner grid mix.",
      "affected_requests_percent": 35.0,
      "potential_savings_kg_co2": 1.5,
      "potential_savings_percent": 8.2,
      "implementation": {
        "action": "Enable Sustain Mode",
        "code_change": "Set routing_mode='sustain_optimized'",
        "dashboard_path": "/settings/sustainability"
      }
    },
    {
      "id": "opt_004",
      "type": "batch_requests",
      "priority": "low",
      "title": "Batch embedding requests",
      "description": "Detected 45 sequential single-item embedding calls that could be batched (max 2048 items per call).",
      "affected_requests_percent": 5.0,
      "potential_savings_kg_co2": 0.4,
      "potential_savings_percent": 2.1,
      "implementation": {
        "action": "Batch embeddings API calls",
        "code_change": "Use input=[text1, text2, ...] instead of sequential calls"
      }
    }
  ],
  "total_potential_savings_kg_co2": 7.9,
  "total_potential_savings_percent": 43.0,
  "analysis_period_days": 30,
  "analyzed_requests": 45000
}

Opportunity Types

Type	Description
model_downgrade	Use smaller models for simpler tasks
enable_caching	Enable semantic caching
green_routing	Route to low-carbon providers/regions
batch_requests	Combine multiple API calls
time_shifting	Defer non-urgent requests to low-carbon times
token_optimization	Reduce prompt/response token count

Priority Levels

Priority	Savings Threshold
high	> 1 kg CO₂/month
medium	0.5 - 1 kg CO₂/month
low	< 0.5 kg CO₂/month

Optimization Summary

For a quick overview of total potential savings:

GET /v1/sustainability/optimization-summary

Response

{
  "total_opportunities": 4,
  "total_potential_savings_kg_co2": 7.9,
  "total_potential_savings_percent": 43.0,
  "high_priority_count": 2,
  "quick_wins": [
    "Enable semantic caching for 17.5% carbon reduction",
    "Use model=auto for intelligent routing"
  ]
}

See Also

• Sustain Mode - Carbon-optimized routing
• Semantic Caching - Cache configuration
• Dashboard API - All metrics