API Access

Fluxtab exposes a small read-only HTTP API for your own account data: usage snapshots, summary, connection metadata, and a CI-friendly spend check. Authenticate with a personal access token from Settings → API access. Tokens start with ftab_ and are shown only once when created.

Why use it

Use the API when you want Fluxtab data outside the dashboard — scripts, internal tools, or a CI/CD spend gate. It never returns provider API keys or Vault material.

Setup

1. Open Settings → API access (account owners on team plans).
2. Create a token with a short label. Copy the ftab_… value immediately; it is not shown again.
3. Store the token as a secret (CI variable, password manager). Revoke it from the same settings page when finished.
4. Call an endpoint with Authorization: Bearer ftab_YOUR_TOKEN.

Missing or invalid tokens return 401. Each token is limited to 60 requests per hour by default (configurable server-side). Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When exceeded, the API returns 429 with Retry-After.

Base URL: https://fluxtab.dev

Endpoints

• GET /api/v1/usage — Usage
• GET /api/v1/summary — Summary
• GET /api/v1/connections — Connections
• GET /api/public/spend-check — Spend check

Authentication

Send your token on every request:

Authorization: Bearer ftab_YOUR_TOKEN

Usage

GET /api/v1/usage

Paginated usage snapshots for a date range. Defaults to the last 30 days.

Query parameters

• start_date, end_date — YYYY-MM-DD (optional; default last 30 days, max 366)
• group_by — day | provider | project (default day)
• page — positive integer (default 1)
• limit — 1–500 (default 100)

Example request

curl "https://fluxtab.dev/api/v1/usage?group_by=day&limit=10" \
  -H "Authorization: Bearer ftab_YOUR_TOKEN"

Example response

{
  "data": [
    {
      "date": "2026-07-15",
      "cost_usd": 12.45,
      "tokens_used": 184200
    }
  ],
  "meta": {
    "start_date": "2026-07-01",
    "end_date": "2026-07-30",
    "group_by": "day"
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 30,
    "total_pages": 3,
    "has_more": true
  }
}

Summary

GET /api/v1/summary

Month-to-date spend, cycle forecast, threshold, and breakdowns by provider and project. Forecast paces in this payload are an estimate, not a guarantee.

Example request

curl "https://fluxtab.dev/api/v1/summary" \
  -H "Authorization: Bearer ftab_YOUR_TOKEN"

Example response

{
  "mtdSpend": 248.32,
  "forecast": {
    "flatPace": 512.1,
    "recentPace": 489.4
  },
  "threshold": 500,
  "byProvider": [
    { "provider": "openai", "spend": 180.2 },
    { "provider": "anthropic", "spend": 68.12 }
  ],
  "byProject": [
    {
      "project_id": "proj_abc",
      "project_label": "Production",
      "spend": 200.0
    }
  ]
}

Connections

GET /api/v1/connections

Metadata for your connected providers. Never returns API keys or Vault material.

Example request

curl "https://fluxtab.dev/api/v1/connections" \
  -H "Authorization: Bearer ftab_YOUR_TOKEN"

Example response

{
  "data": [
    {
      "provider": "openai",
      "label": "Prod org",
      "last_synced_at": "2026-08-01T12:04:11.000Z",
      "native_limit_status": "set"
    },
    {
      "provider": "openrouter",
      "label": null,
      "last_synced_at": "2026-08-01T11:58:02.000Z",
      "native_limit_status": "unknown"
    }
  ]
}

Spend check

GET /api/public/spend-check

CI-friendly spend check for the current billing cycle. Optional budget query overrides your stored alert threshold for overBudget only.

Query parameters

• budget — non-negative number (optional override for overBudget)

Example request

curl "https://fluxtab.dev/api/public/spend-check?budget=500" \
  -H "Authorization: Bearer ftab_YOUR_TOKEN"

Example response

{
  "mtdSpend": 248.32,
  "forecast": {
    "flatPace": 512.1,
    "recentPace": 489.4
  },
  "threshold": 500,
  "overBudget": false,
  "byProvider": [
    { "provider": "openai", "spend": 180.2 },
    { "provider": "anthropic", "spend": 68.12 }
  ]
}