Cloud FinOps API Documentation

Parse brainiac-billing-v1 charges, score daily cost anomalies, allocate spend, and forecast from the supplied export. No cloud account is connected. Payment is the exact USDC price on Base with x402.

{
  "csv": "date,service,cost,currency,tags\n2026-01-01,compute,10,USD,team=platform\n2026-01-02,storage,5,USD,\n"
}

{
  "checkedAt": "2026-11-02T19:00:00.000Z",
  "accountConnected": false,
  "infrastructureChanged": false,
  "format": "brainiac-billing-v1",
  "status": "parsed",
  "currencies": [
    "USD"
  ],
  "rowCount": 2,
  "rows": [
    {
      "date": "2026-01-01",
      "service": "compute",
      "region": "",
      "account": "",
      "resourceId": "",
      "resourceType": "",
      "usageQuantity": null,
      "usageUnit": "",
      "cost": 10,
      "currency": "USD",
      "tags": "team=platform"
    },
    {
      "date": "2026-01-02",
      "service": "storage",
      "region": "",
      "account": "",
      "resourceId": "",
      "resourceType": "",
      "usageQuantity": null,
      "usageUnit": "",
      "cost": 5,
      "currency": "USD",
      "tags": ""
    }
  ],
  "findings": [],
  "limitations": [
    "No cloud account was connected and no infrastructure was changed.",
    "Costs and forecasts use only figures supplied in the request.",
    "Provider list prices are not added, and no saving is claimed without a supplied cost.",
    "The billing format is brainiac-billing-v1. Native provider exports are not accepted."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/cloud-finops/cloud-billing-csv-parse" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "csv": "date,service,cost,currency,tags\n2026-01-01,compute,10,USD,team=platform\n2026-01-02,storage,5,USD,\n"
}
JSON

{
  "csv": "date,service,cost,currency\n2026-01-01,compute,10,USD\n2026-01-02,compute,10,USD\n2026-01-03,compute,10,USD\n2026-01-04,compute,10,USD\n2026-01-05,compute,10,USD\n2026-01-06,compute,10,USD\n2026-01-07,compute,10,USD\n2026-01-08,compute,10,USD\n2026-01-09,compute,10,USD\n2026-01-10,compute,10,USD\n2026-01-11,compute,10,USD\n2026-01-12,compute,10,USD\n2026-01-13,compute,10,USD\n2026-01-14,compute,10,USD\n2026-01-15,compute,200,USD\n"
}

{
  "checkedAt": "2026-11-02T19:00:00.000Z",
  "accountConnected": false,
  "infrastructureChanged": false,
  "status": "anomalies",
  "series": [
    {
      "currency": "USD",
      "status": "anomalies",
      "days": 15,
      "mean": 22.666667,
      "stdev": 49.057789,
      "anomalies": [
        {
          "date": "2026-01-15",
          "cost": 200,
          "zScore": 3.6148
        }
      ]
    }
  ],
  "findings": [
    {
      "kind": "extracted",
      "code": "anomaly_method",
      "detail": "USD uses a sample z-score. Mean 22.666667, sample standard deviation 49.057789. A day is flagged when the absolute z-score is at least 3."
    }
  ],
  "limitations": [
    "No cloud account was connected and no infrastructure was changed.",
    "Costs and forecasts use only figures supplied in the request.",
    "Provider list prices are not added, and no saving is claimed without a supplied cost.",
    "The billing format is brainiac-billing-v1. Native provider exports are not accepted.",
    "An anomaly is a daily total whose sample z-score is at least 3. It is not a root-cause diagnosis."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/cloud-finops/cloud-cost-anomaly-detect" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "csv": "date,service,cost,currency\n2026-01-01,compute,10,USD\n2026-01-02,compute,10,USD\n2026-01-03,compute,10,USD\n2026-01-04,compute,10,USD\n2026-01-05,compute,10,USD\n2026-01-06,compute,10,USD\n2026-01-07,compute,10,USD\n2026-01-08,compute,10,USD\n2026-01-09,compute,10,USD\n2026-01-10,compute,10,USD\n2026-01-11,compute,10,USD\n2026-01-12,compute,10,USD\n2026-01-13,compute,10,USD\n2026-01-14,compute,10,USD\n2026-01-15,compute,200,USD\n"
}
JSON

{
  "rows": [
    {
      "date": "2026-01-15",
      "service": "compute",
      "cost": 100,
      "currency": "USD"
    },
    {
      "date": "2026-02-15",
      "service": "compute",
      "cost": 110,
      "currency": "USD"
    },
    {
      "date": "2026-03-15",
      "service": "storage",
      "cost": 120,
      "currency": "USD"
    }
  ]
}

{
  "checkedAt": "2026-11-02T19:00:00.000Z",
  "accountConnected": false,
  "infrastructureChanged": false,
  "status": "grouped",
  "groups": [
    {
      "currency": "USD",
      "key": "compute",
      "cost": 210,
      "share": 0.636364
    },
    {
      "currency": "USD",
      "key": "storage",
      "cost": 120,
      "share": 0.363636
    }
  ],
  "trend": [
    {
      "currency": "USD",
      "status": "compared",
      "previousMonth": "2026-02",
      "latestMonth": "2026-03",
      "previousCost": 110,
      "latestCost": 120,
      "change": 10
    }
  ],
  "groupedBy": "service",
  "findings": [
    {
      "kind": "extracted",
      "code": "no_fx",
      "detail": "Currencies are not converted."
    }
  ],
  "limitations": [
    "No cloud account was connected and no infrastructure was changed.",
    "Costs and forecasts use only figures supplied in the request.",
    "Provider list prices are not added, and no saving is claimed without a supplied cost.",
    "The billing format is brainiac-billing-v1. Native provider exports are not accepted."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/cloud-finops/cloud-spend-breakdown" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "rows": [
    {
      "date": "2026-01-15",
      "service": "compute",
      "cost": 100,
      "currency": "USD"
    },
    {
      "date": "2026-02-15",
      "service": "compute",
      "cost": 110,
      "currency": "USD"
    },
    {
      "date": "2026-03-15",
      "service": "storage",
      "cost": 120,
      "currency": "USD"
    }
  ]
}
JSON

{
  "cpuThreshold": 5,
  "minimumDays": 14,
  "resources": [
    {
      "resourceId": "i-idle",
      "resourceType": "compute",
      "daysObserved": 14,
      "cpuPercent": 2,
      "cost": 40,
      "currency": "USD"
    },
    {
      "resourceId": "i-unknown",
      "resourceType": "compute",
      "daysObserved": 14,
      "cost": 40,
      "currency": "USD"
    }
  ]
}

{
  "checkedAt": "2026-11-02T19:00:00.000Z",
  "accountConnected": false,
  "infrastructureChanged": false,
  "status": "idle_observed",
  "resources": [
    {
      "resourceId": "i-idle",
      "status": "idle",
      "cpuPercent": 2,
      "daysObserved": 14,
      "suppliedCost": 40,
      "currency": "USD"
    },
    {
      "resourceId": "i-unknown",
      "status": "insufficient",
      "cpuPercent": null,
      "daysObserved": 14,
      "suppliedCost": 40,
      "currency": "USD"
    }
  ],
  "findings": [
    {
      "kind": "extracted",
      "code": "idle_rule",
      "detail": "Compute is idle only when daysObserved is at least 14 and cpuPercent is below the supplied threshold 5. Missing CPU is not treated as idle."
    }
  ],
  "limitations": [
    "No cloud account was connected and no infrastructure was changed.",
    "Costs and forecasts use only figures supplied in the request.",
    "Provider list prices are not added, and no saving is claimed without a supplied cost.",
    "The billing format is brainiac-billing-v1. Native provider exports are not accepted."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/cloud-finops/idle-resource-detect" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "cpuThreshold": 5,
  "minimumDays": 14,
  "resources": [
    {
      "resourceId": "i-idle",
      "resourceType": "compute",
      "daysObserved": 14,
      "cpuPercent": 2,
      "cost": 40,
      "currency": "USD"
    },
    {
      "resourceId": "i-unknown",
      "resourceType": "compute",
      "daysObserved": 14,
      "cost": 40,
      "currency": "USD"
    }
  ]
}
JSON

{
  "minimumDays": 7,
  "volumes": [
    {
      "resourceId": "vol-free",
      "attached": false,
      "daysObserved": 10,
      "storageGb": 100,
      "cost": 8,
      "currency": "USD"
    },
    {
      "resourceId": "vol-unknown",
      "attached": true,
      "daysObserved": 10,
      "storageGb": 100
    }
  ]
}

{
  "checkedAt": "2026-11-02T19:00:00.000Z",
  "accountConnected": false,
  "infrastructureChanged": false,
  "status": "unused_observed",
  "volumes": [
    {
      "resourceId": "vol-free",
      "status": "unused",
      "suppliedCost": 8,
      "currency": "USD"
    },
    {
      "resourceId": "vol-unknown",
      "status": "insufficient",
      "suppliedCost": null,
      "currency": ""
    }
  ],
  "findings": [
    {
      "kind": "extracted",
      "code": "storage_rule",
      "detail": "A volume is unused only when daysObserved is at least 7 and the request says it is unattached or usedGb is 0 with storage present. Missing usage is not treated as unused."
    }
  ],
  "limitations": [
    "No cloud account was connected and no infrastructure was changed.",
    "Costs and forecasts use only figures supplied in the request.",
    "Provider list prices are not added, and no saving is claimed without a supplied cost.",
    "The billing format is brainiac-billing-v1. Native provider exports are not accepted."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/cloud-finops/unused-storage-detect" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "minimumDays": 7,
  "volumes": [
    {
      "resourceId": "vol-free",
      "attached": false,
      "daysObserved": 10,
      "storageGb": 100,
      "cost": 8,
      "currency": "USD"
    },
    {
      "resourceId": "vol-unknown",
      "attached": true,
      "daysObserved": 10,
      "storageGb": 100
    }
  ]
}
JSON

{
  "options": [
    {
      "name": "a",
      "hourlyPrice": 0.1,
      "hours": 720,
      "currency": "USD"
    },
    {
      "name": "b",
      "hourlyPrice": 0.08,
      "hours": 720,
      "currency": "USD"
    }
  ]
}

{
  "checkedAt": "2026-11-02T19:00:00.000Z",
  "accountConnected": false,
  "infrastructureChanged": false,
  "status": "compared",
  "options": [
    {
      "name": "a",
      "currency": "USD",
      "hourlyPrice": 0.1,
      "hours": 720,
      "cost": 72
    },
    {
      "name": "b",
      "currency": "USD",
      "hourlyPrice": 0.08,
      "hours": 720,
      "cost": 57.6
    }
  ],
  "lowerCost": "b",
  "difference": 14.4,
  "findings": [
    {
      "kind": "extracted",
      "code": "compute_compared",
      "detail": "b costs 14.4 less than the next supplied option for the supplied hours. The prices were supplied and are not a provider list."
    }
  ],
  "limitations": [
    "No cloud account was connected and no infrastructure was changed.",
    "Costs and forecasts use only figures supplied in the request.",
    "Provider list prices are not added, and no saving is claimed without a supplied cost.",
    "The billing format is brainiac-billing-v1. Native provider exports are not accepted."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/cloud-finops/compute-cost-compare" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "options": [
    {
      "name": "a",
      "hourlyPrice": 0.1,
      "hours": 720,
      "currency": "USD"
    },
    {
      "name": "b",
      "hourlyPrice": 0.08,
      "hours": 720,
      "currency": "USD"
    }
  ]
}
JSON

{
  "rows": [
    {
      "date": "2026-01-15",
      "service": "compute",
      "cost": 100,
      "currency": "USD"
    },
    {
      "date": "2026-02-15",
      "service": "compute",
      "cost": 110,
      "currency": "USD"
    },
    {
      "date": "2026-03-15",
      "service": "storage",
      "cost": 120,
      "currency": "USD"
    }
  ]
}

{
  "checkedAt": "2026-11-02T19:00:00.000Z",
  "accountConnected": false,
  "infrastructureChanged": false,
  "status": "forecast",
  "forecasts": [
    {
      "currency": "USD",
      "status": "forecast",
      "method": "monthly_line",
      "forecast": 130,
      "low": 130,
      "high": 130,
      "detail": "Ordinary least squares on 3 supplied monthly totals. The next month is point 4. The band is one residual standard deviation, not a probability."
    }
  ],
  "findings": [
    {
      "kind": "extracted",
      "code": "forecast_method",
      "detail": "Ordinary least squares on 3 supplied monthly totals. The next month is point 4. The band is one residual standard deviation, not a probability."
    }
  ],
  "limitations": [
    "No cloud account was connected and no infrastructure was changed.",
    "Costs and forecasts use only figures supplied in the request.",
    "Provider list prices are not added, and no saving is claimed without a supplied cost.",
    "The billing format is brainiac-billing-v1. Native provider exports are not accepted."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/cloud-finops/monthly-cloud-cost-forecast" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "rows": [
    {
      "date": "2026-01-15",
      "service": "compute",
      "cost": 100,
      "currency": "USD"
    },
    {
      "date": "2026-02-15",
      "service": "compute",
      "cost": 110,
      "currency": "USD"
    },
    {
      "date": "2026-03-15",
      "service": "storage",
      "cost": 120,
      "currency": "USD"
    }
  ]
}
JSON

{
  "rows": [
    {
      "date": "2026-01-15",
      "service": "compute",
      "cost": 100,
      "currency": "USD"
    },
    {
      "date": "2026-02-15",
      "service": "compute",
      "cost": 110,
      "currency": "USD"
    },
    {
      "date": "2026-03-15",
      "service": "storage",
      "cost": 120,
      "currency": "USD"
    }
  ],
  "budget": {
    "amount": 300,
    "currency": "USD",
    "periodStart": "2026-01-01",
    "periodEnd": "2026-03-31"
  }
}

{
  "checkedAt": "2026-11-02T19:00:00.000Z",
  "accountConnected": false,
  "infrastructureChanged": false,
  "status": "partial",
  "currency": "USD",
  "actual": 330,
  "budget": 300,
  "variance": 30,
  "coverageDays": 3,
  "periodDays": 90,
  "findings": [
    {
      "kind": "insufficient",
      "code": "budget_partial",
      "detail": "The period has 90 days and the charges cover 3. The variance uses only the supplied rows."
    },
    {
      "kind": "extracted",
      "code": "budget_variance",
      "detail": "Actual 330 minus budget 300 is 30 USD."
    }
  ],
  "limitations": [
    "No cloud account was connected and no infrastructure was changed.",
    "Costs and forecasts use only figures supplied in the request.",
    "Provider list prices are not added, and no saving is claimed without a supplied cost.",
    "The billing format is brainiac-billing-v1. Native provider exports are not accepted."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/cloud-finops/budget-variance-analyze" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "rows": [
    {
      "date": "2026-01-15",
      "service": "compute",
      "cost": 100,
      "currency": "USD"
    },
    {
      "date": "2026-02-15",
      "service": "compute",
      "cost": 110,
      "currency": "USD"
    },
    {
      "date": "2026-03-15",
      "service": "storage",
      "cost": 120,
      "currency": "USD"
    }
  ],
  "budget": {
    "amount": 300,
    "currency": "USD",
    "periodStart": "2026-01-01",
    "periodEnd": "2026-03-31"
  }
}
JSON

{
  "tagKey": "team",
  "rows": [
    {
      "date": "2026-01-01",
      "service": "compute",
      "cost": 70,
      "currency": "USD",
      "tags": [
        {
          "key": "team",
          "value": "platform"
        }
      ]
    },
    {
      "date": "2026-01-02",
      "service": "compute",
      "cost": 30,
      "currency": "USD"
    }
  ]
}

{
  "checkedAt": "2026-11-02T19:00:00.000Z",
  "accountConnected": false,
  "infrastructureChanged": false,
  "status": "allocated",
  "tagKey": "team",
  "groups": [
    {
      "currency": "USD",
      "tag": "platform",
      "cost": 70,
      "share": 0.7
    }
  ],
  "unallocated": [
    {
      "currency": "USD",
      "cost": 30,
      "share": 0.3
    }
  ],
  "findings": [
    {
      "kind": "extracted",
      "code": "allocation_rule",
      "detail": "Costs are grouped by the supplied tag team. Charges without that tag stay unallocated and were not assigned to a group."
    }
  ],
  "limitations": [
    "No cloud account was connected and no infrastructure was changed.",
    "Costs and forecasts use only figures supplied in the request.",
    "Provider list prices are not added, and no saving is claimed without a supplied cost.",
    "The billing format is brainiac-billing-v1. Native provider exports are not accepted."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/cloud-finops/cloud-cost-allocation" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "tagKey": "team",
  "rows": [
    {
      "date": "2026-01-01",
      "service": "compute",
      "cost": 70,
      "currency": "USD",
      "tags": [
        {
          "key": "team",
          "value": "platform"
        }
      ]
    },
    {
      "date": "2026-01-02",
      "service": "compute",
      "cost": 30,
      "currency": "USD"
    }
  ]
}
JSON

{
  "rows": [
    {
      "date": "2026-01-15",
      "service": "compute",
      "cost": 100,
      "currency": "USD"
    },
    {
      "date": "2026-02-15",
      "service": "compute",
      "cost": 110,
      "currency": "USD"
    },
    {
      "date": "2026-03-15",
      "service": "storage",
      "cost": 120,
      "currency": "USD"
    }
  ],
  "resources": [
    {
      "resourceId": "i-idle",
      "resourceType": "compute",
      "daysObserved": 14,
      "cpuPercent": 2,
      "cost": 40,
      "currency": "USD"
    }
  ],
  "cpuThreshold": 5,
  "minimumDays": 14,
  "options": [
    {
      "name": "a",
      "hourlyPrice": 0.1,
      "hours": 720,
      "currency": "USD"
    },
    {
      "name": "b",
      "hourlyPrice": 0.08,
      "hours": 720,
      "currency": "USD"
    }
  ]
}

{
  "checkedAt": "2026-11-02T19:00:00.000Z",
  "accountConnected": false,
  "infrastructureChanged": false,
  "summary": "The report uses only the supplied export and usage fields. No account was connected and no infrastructure was changed.",
  "sections": [
    {
      "name": "billing",
      "status": "parsed"
    },
    {
      "name": "anomalies",
      "status": "insufficient"
    },
    {
      "name": "breakdown",
      "status": "grouped"
    },
    {
      "name": "idle",
      "status": "idle_observed"
    },
    {
      "name": "storage",
      "status": "not_supplied"
    },
    {
      "name": "compare",
      "status": "compared"
    },
    {
      "name": "forecast",
      "status": "forecast"
    },
    {
      "name": "budget",
      "status": "not_supplied"
    },
    {
      "name": "allocation",
      "status": "not_supplied"
    }
  ],
  "recommendations": [
    {
      "code": "idle_compute",
      "resourceId": "i-idle",
      "evidence": "CPU 2% across 14 supplied days.",
      "assumption": "The resource stays idle only while CPU remains below the supplied threshold for the supplied window.",
      "suppliedCost": 40,
      "currency": "USD",
      "detail": "The figure is the cost supplied for this resource, not a provider price."
    },
    {
      "code": "supplied_price_difference",
      "resourceId": "b",
      "evidence": "b costs 14.4 less than the next supplied option for the supplied hours. The prices were supplied and are not a provider list.",
      "assumption": "The hours stay at the supplied figure and the supplied hourly prices do not change.",
      "suppliedCost": 14.4,
      "currency": "USD",
      "detail": "The difference uses only the prices and hours in the request."
    }
  ],
  "findings": [
    {
      "kind": "insufficient",
      "code": "anomaly_insufficient",
      "detail": "USD has 3 daily totals. A modified check needs at least 8 days, so no anomaly was scored."
    },
    {
      "kind": "extracted",
      "code": "idle_rule",
      "detail": "Compute is idle only when daysObserved is at least 14 and cpuPercent is below the supplied threshold 5. Missing CPU is not treated as idle."
    },
    {
      "kind": "extracted",
      "code": "compute_compared",
      "detail": "b costs 14.4 less than the next supplied option for the supplied hours. The prices were supplied and are not a provider list."
    }
  ],
  "limitations": [
    "No cloud account was connected and no infrastructure was changed.",
    "Costs and forecasts use only figures supplied in the request.",
    "Provider list prices are not added, and no saving is claimed without a supplied cost.",
    "The billing format is brainiac-billing-v1. Native provider exports are not accepted."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/cloud-finops/cloud-cost-optimization-report" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "rows": [
    {
      "date": "2026-01-15",
      "service": "compute",
      "cost": 100,
      "currency": "USD"
    },
    {
      "date": "2026-02-15",
      "service": "compute",
      "cost": 110,
      "currency": "USD"
    },
    {
      "date": "2026-03-15",
      "service": "storage",
      "cost": 120,
      "currency": "USD"
    }
  ],
  "resources": [
    {
      "resourceId": "i-idle",
      "resourceType": "compute",
      "daysObserved": 14,
      "cpuPercent": 2,
      "cost": 40,
      "currency": "USD"
    }
  ],
  "cpuThreshold": 5,
  "minimumDays": 14,
  "options": [
    {
      "name": "a",
      "hourlyPrice": 0.1,
      "hours": 720,
      "currency": "USD"
    },
    {
      "name": "b",
      "hourlyPrice": 0.08,
      "hours": 720,
      "currency": "USD"
    }
  ]
}
JSON