API Reference

Authentication

All API requests require an API key passed in the Authorization header. Generate your API key from Settings in the Finopscraft dashboard.

Authorization: Bearer foc_live_xxxxxxxxxxxxxxxxxxxxxxxx

API keys have read-only access to your account data. Treat your API key as a secret. If compromised, revoke it immediately from Settings and generate a new one.

Base URL

https://api.finopscraft.com/v1

All endpoints return JSON. Timestamps use ISO 8601 format. Currency values are in USD unless specified.

Endpoints

GET /forecast

Returns the current forecast for your connected accounts.

Parameter	Type	Required	Description
account_id	string	No	Filter to a specific connected account. Omit for all accounts.
service	string	No	Filter by cloud service (e.g. AmazonEC2).
region	string	No	Filter by region (e.g. us-east-1).
days	integer	No	Forecast window: 30, 90, or 180 (tier-dependent). Defaults to 30.

GET /v1/forecast?days=30&service=AmazonEC2

{
  "period_start": "2026-07-04",
  "period_end": "2026-08-03",
  "forecast_usd": 18420.00,
  "confidence_low_usd": 16900.00,
  "confidence_high_usd": 20100.00,
  "forecast_error_pct": 7.8,
  "items": [
    {
      "service": "AmazonEC2",
      "region": "us-east-1",
      "forecast_usd": 11240.00,
      "trend": "increasing",
      "vs_last_period_pct": 12.4
    }
  ]
}

GET /waste

Returns the current waste report: flagged resources with estimated monthly cost and recommended action.

Parameter	Type	Required	Description
account_id	string	No	Filter to a specific account.
category	string	No	idle_compute, overprovisioned_storage, or orphaned.
min_monthly_usd	number	No	Only return items above this monthly cost threshold.

GET /v1/waste?category=idle_compute&min_monthly_usd=20

{
  "total_waste_usd": 465.00,
  "items": [
    {
      "resource_id": "i-0a7f3b81c",
      "resource_type": "EC2 t3.large",
      "account_id": "123456789012",
      "region": "us-east-1",
      "monthly_usd": 61.00,
      "category": "idle_compute",
      "flag_reason": "CPU < 5% for 14 days",
      "suggested_action": "Terminate or schedule stop policy"
    }
  ]
}

GET /accounts

Returns a list of connected cloud accounts.

GET /v1/accounts

{
  "accounts": [
    {
      "id": "acc_01jxy9",
      "provider": "aws",
      "display_name": "Production AWS",
      "status": "active",
      "last_synced_at": "2026-07-04T06:00:00Z"
    }
  ]
}

Rate limits

The API is rate-limited to 100 requests per minute per API key. Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers.

Error responses

HTTP status	Meaning
401	Invalid or missing API key
403	API access not available on your current tier
404	Account or resource not found
429	Rate limit exceeded
500	Unexpected server error. Try again or contact support.