API & Developers – MetaFinOps

Quick Start

Everything you need to make your first API call.

Authentication

API key-based authentication via Bearer tokens. Generate keys from your dashboard under Settings → API Keys.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.metafinops.com/v1/costs/summary

Base URL

All API requests are made to the following base URL. All communication is encrypted over HTTPS.

https://api.metafinops.com/v1

Rate Limits

Rate limits scale with your plan. Limits are applied per API key and tracked via response headers.

Starter1,000 req/min

Growth5,000 req/min

EnterpriseUnlimited

Core API Endpoints

Access cost data, GPU metrics, token analytics, budgets, anomalies, and recommendations.

GET /v1/costs/summary Retrieve cost summary by date range

GET /v1/costs/by-service Cost breakdown by cloud service

GET /v1/gpu/utilization GPU utilization metrics

GET /v1/gpu/idle Idle GPU instance detection

GET /v1/tokens/usage Token consumption by model/provider

GET /v1/tokens/cost Token cost analytics

POST /v1/budgets Create budget policy

GET /v1/budgets/{id}/alerts Budget alert history

GET /v1/anomalies Detected cost anomalies

POST /v1/reports/generate Generate cost report

GET /v1/carbon/footprint Carbon emissions data

GET /v1/recommendations Cost optimization recommendations

SDKs & Libraries

Official client libraries to get you up and running in minutes.

Python SDK

$ pip install metafinops

from metafinops import Client

client = Client(api_key="YOUR_API_KEY")
costs = client.costs.summary(
    start="2026-03-01",
    end="2026-03-31"
)
print(costs.total)

Node.js SDK

$ npm install @metafinops/sdk

import { MetaFinOps } from "@metafinops/sdk";

const client = new MetaFinOps("YOUR_API_KEY");
const costs = await client.costs.summary({
  start: "2026-03-01",
  end: "2026-03-31",
});

Go SDK

$ go get github.com/metafinops/go-sdk

import mfo "github.com/metafinops/go-sdk"

client := mfo.NewClient("YOUR_API_KEY")
costs, err := client.Costs.Summary(&mfo.SummaryParams{
    Start: "2026-03-01",
    End:   "2026-03-31",
})

Terraform Provider

terraform {
  required_providers {
    metafinops = {
      source  = "metafinops/metafinops"
      version = "~> 1.0"
    }
  }
}

provider "metafinops" {
  api_key = var.metafinops_api_key
}

Webhooks

Receive real-time notifications when key events occur in your MetaFinOps account.

Supported Events

cost.anomaly.detected Unusual spend detected

budget.threshold.reached Budget limit hit

gpu.idle.detected Idle GPU found

report.generated Report ready to download

Security & Reliability

HMAC-SHA256 Signatures — Every payload is signed with your webhook secret. Verify the X-MetaFinOps-Signature header.
Automatic Retries — Failed deliveries are retried up to 5 times with exponential backoff (5s, 30s, 2m, 15m, 1h).
Event Log — Full delivery history available in your dashboard for debugging.

Example Payload

{
  "event": "cost.anomaly.detected",
  "timestamp": "2026-03-31T14:22:00Z",
  "data": {
    "anomaly_id": "ano_8xK2mP",
    "service": "aws-ec2",
    "expected_cost": 1240.00,
    "actual_cost": 3870.50,
    "severity": "high",
    "account": "prod-us-east-1"
  }
}

Verification tip: Compute HMAC-SHA256 of the raw request body using your webhook secret and compare it to the X-MetaFinOps-Signature header value.

API Response Format

All responses follow a consistent envelope structure for easy parsing.

{
  "status": "success",
  "data": {
    "total_cost": 48520.75,
    "currency": "USD",
    "period": {
      "start": "2026-03-01",
      "end": "2026-03-31"
    },
    "services": [ ... ]
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5",
    "timestamp": "2026-03-31T10:15:30Z"
  }
}

API & Developer Portal