API Authentication

Overview

The CostOptix API uses API keys. A key belongs to your organisation and carries permissions that control what it can do. Every plan includes API access, with a daily call limit:

Plan	API calls / day
Starter	100
Growth	500
Professional	1,000
Business	10,000
Enterprise	Unlimited

Limits reset at 00:00 UTC.

Creating a key

Go to Settings → API Keys and click Create API Key.
Give it a name you will recognise, such as CI pipeline or Grafana.
Pick its permissions.
Optionally set an expiry: 7 days, 30 days, 90 days or 1 year.
Copy the key straight away. It is shown only once.

Permissions

Permission	What it allows
`read`	View cost data, reports, anomalies and budgets
`write`	Change accounts and settings
`admin`	Full administrative access. Only admins can create these.
`k8s:ingest`	Only lets the Kubernetes agent push cluster metrics
`host:ingest`	Only lets the host agent push machine metrics
`llm:ingest`	Only lets AI coding tools push usage telemetry
`metrics:ingest`	Only lets your systems send Unit Economics metric values

The four ingest permissions are deliberately narrow. A key that holds only ingest permissions can push that data and nothing else: it cannot read costs or change settings. Adding read, write or admin to the same key removes that limit, so keep ingest keys separate. That makes them safe to leave on a cluster, a machine or a developer laptop. The guided setup on the Kubernetes, Hosts and LLM Usage pages creates the right key for you.

Using a key

Send the key in the X-API-Key header:

curl -H "X-API-Key: <your-key>" \
  https://costoptix.com/api/v1/auth/info

Base URL:

https://costoptix.com/api/v1

Examples

List connected accounts:

curl -H "X-API-Key: <your-key>" \
  https://costoptix.com/api/v1/accounts

Get the org-wide overview for a month:

curl -H "X-API-Key: <your-key>" \
  "https://costoptix.com/api/v1/overview?month=2026-09"

Leave out month for the current month.

Treat API keys like passwords. Never put them in client-side code or a public repository.

Rotating and revoking keys

Revoke a key at any time from Settings → API Keys. Revocation is immediate. To rotate without downtime:

Create the new key.
Update everything that uses the old one.
Revoke the old key.

Agent keys show their expiry date in the agent health panel on the Kubernetes and Hosts pages, so you can replace them before they lapse.

Rate limits

When the daily limit is reached, the API returns 429 Too Many Requests with details of the limit and when it resets:

{
  "success": false,
  "error": "daily API limit exceeded (1000/1000)",
  "data": {
    "error_type": "rate_limit_exceeded",
    "rate_limit": {
      "limit": 1000,
      "used": 1000,
      "remaining": 0,
      "reset_time": "2026-10-05T00:00:00Z",
      "resets_in_seconds": 3600
    },
    "upgrade_available": true
  }
}

Errors

Errors use the same shape:

{
  "success": false,
  "error": "Description of what went wrong"
}

Status	Meaning
`200`	Success
`400`	Bad request. Check your parameters.
`401`	Missing or invalid API key
`403`	The key lacks the permission, or your plan does not include the feature
`429`	Daily limit reached
`500`	Server error

Getting Started

Connect Your Sources

See Your Spend

Act On It

Tools and Alerts

API Reference

Account

Security

API Authentication

Overview

Creating a key

Permissions

Using a key

Examples

Rotating and revoking keys

Rate limits

Errors

​Overview

​Creating a key

​Permissions

​Using a key

​Examples

​Rotating and revoking keys

​Rate limits

​Errors

Overview

Creating a key

Permissions

Using a key

Examples

Rotating and revoking keys

Rate limits

Errors