Usage API

Track generation usage, spending by modality and model, transaction history, and daily breakdowns.

GET /v1/usage

Get a usage summary for a time period, broken down by modality and model. Requires credits:read scope.

Query parameters

Parameter	Type	Required	Description
`from`	string (date)	Yes	Start date (ISO 8601, e.g. `2026-02-01`).
`to`	string (date)	Yes	End date (inclusive).
`key_id`	string	No	Filter by API key ID.

Response fields

Field	Type	Description
`total_cost`	object	Total spend. Contains `micro`, `display`, `currency`.
`generation_count`	integer	Total number of successful generations.
`by_modality`	array	Breakdown by modality (image, video, voice, music).
`by_model`	array	Breakdown by model key.

Code examples

curl

curl "https://api.fairstack.ai/v1/usage?from=2026-02-01&to=2026-02-28" \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY"

Python

from fairstack import FairStack

client = FairStack(api_key="fs_live_YOUR_KEY")

usage = client.usage.get(
    from_date="2026-02-01",
    to_date="2026-02-28"
)
print(usage.total_cost.display)  # "$4.52"
print(usage.generation_count)    # 347

for breakdown in usage.by_modality:
    print(f"{breakdown.modality}: {breakdown.count} generations, {breakdown.cost.display}")

Node.js

import { FairStack } from "fairstack";

const client = new FairStack({ apiKey: "fs_live_YOUR_KEY" });

const usage = await client.usage.get({
  from: "2026-02-01",
  to: "2026-02-28",
});
console.log(usage.totalCost.display);   // "$4.52"
console.log(usage.generationCount);     // 347

for (const b of usage.byModality) {
  console.log(`${b.modality}: ${b.count} generations, ${b.cost.display}`);
}

Response

{
  "from": "2026-02-01",
  "to": "2026-02-28",
  "total_cost": {
    "micro": 4520000,
    "display": "$4.52",
    "currency": "USD"
  },
  "generation_count": 347,
  "by_modality": [
    { "modality": "image", "count": 280, "cost": { "micro": 1120000, "display": "$1.12" } },
    { "modality": "video", "count": 12, "cost": { "micro": 1440000, "display": "$1.44" } },
    { "modality": "voice", "count": 45, "cost": { "micro": 45000, "display": "$0.045" } },
    { "modality": "music", "count": 10, "cost": { "micro": 1000000, "display": "$1.00" } }
  ],
  "by_model": [
    { "model": "z-image-turbo", "count": 200, "cost": { "micro": 800000, "display": "$0.80" } },
    { "model": "gpt-image-1.5-t2i", "count": 80, "cost": { "micro": 320000, "display": "$0.32" } }
  ]
}

GET /v1/usage/transactions

List individual transactions: generations, top-ups, and refunds. Sorted by most recent first.

Query parameters

Parameter	Type	Required	Description
`type`	string	No	Filter: `"generation"`, `"top_up"`, `"refund"`.
`modality`	string	No	Filter by modality: `"image"`, `"video"`, `"voice"`, `"music"`.
`limit`	integer	No	Max results (1-100). Default: 20.
`cursor`	string	No	Pagination cursor.

curl "https://api.fairstack.ai/v1/usage/transactions?limit=5" \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY"

{
  "transactions": [
    {
      "id": "gen_abc123",
      "type": "generation",
      "model": "z-image-turbo",
      "modality": "image",
      "cost": { "micro": 4000, "display": "$0.004" },
      "status": "completed",
      "created_at": "2026-03-10T14:30:00Z"
    },
    {
      "id": "job_def456",
      "type": "generation",
      "model": "wan-2-1-t2v",
      "modality": "video",
      "cost": { "micro": 48000, "display": "$0.048" },
      "status": "completed",
      "created_at": "2026-03-10T14:25:00Z"
    },
    {
      "id": "txn_topup_789",
      "type": "top_up",
      "cost": { "micro": -10000000, "display": "-$10.00" },
      "status": "completed",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ],
  "has_more": true,
  "cursor": "cursor_xyz"
}

GET /v1/usage/daily

Get daily usage breakdown for charting and trend analysis.

Query parameters

Parameter	Type	Required	Description
`from`	string (date)	Yes	Start date.
`to`	string (date)	Yes	End date.

curl "https://api.fairstack.ai/v1/usage/daily?from=2026-03-01&to=2026-03-10" \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY"

{
  "days": [
    { "date": "2026-03-01", "count": 45, "cost": { "micro": 320000, "display": "$0.32" } },
    { "date": "2026-03-02", "count": 38, "cost": { "micro": 280000, "display": "$0.28" } },
    { "date": "2026-03-03", "count": 52, "cost": { "micro": 410000, "display": "$0.41" } }
  ]
}

Next steps

Platform API -- check credits and manage API keys
Pricing Docs -- how pricing works
API Reference -- all endpoints

Platform API Model Overview