Usage and credits

The API charges in credits. Two endpoints tell you where they went: GET /v1/credits for what is left, and GET /v1/usage for what you spent. Both take your API key, the same one you generate with.

---

Your balance

curl -s "https://agents.lumalabs.ai/v1/credits" \
  -H "Authorization: Bearer $LUMA_API_KEY"

{
  "balance_credits": 49512
}

balance_credits is your team’s whole balance: every credit granted or bought, less everything spent, less the credits held right now for generations still running. A hold becomes a charge or is released when the generation finishes. To convert it to dollars, see Credits and dollars.

---

What you spent

GET /v1/usage reports settled charges only. A generation still running is not in it until it finishes.

Parameter	Meaning
group_by	model, user, session or api_key. Omit it for the summary.
start, end	An explicit window, ISO-8601. start is inclusive and required with end; end is exclusive and defaults to now; a time without an offset is UTC. At most 92 days. Omit both for your current billing period.
user_id	With group_by=session: keep one end user’s sessions.

Every response echoes its window as period_start and period_end.

The summary

curl -s "https://agents.lumalabs.ai/v1/usage" \
  -H "Authorization: Bearer $LUMA_API_KEY"

{
  "period_start": "2026-10-01T00:00:00+00:00",
  "period_end": "2026-11-01T00:00:00+00:00",
  "plan_slug": "api-paygo",
  "included_credits": 0,
  "overage_rate": null,
  "total_credits_used": 31,
  "included_credits_remaining": 49602,
  "overage_credits": 0,
  "total_generations": 2,
  "total_sessions": 2
}

• total_credits_used and total_generations count POST /v1/generations and Scenes boards made with the API. Spend in the Luma app or over MCP is not in them.
• plan_slug, included_credits, overage_rate and included_credits_remaining describe your plan for the current billing period. They are null when you pass start or end, and when your team has no plan.
• overage_rate is the price of a credit past your allowance, in USD per credit, as a decimal string. It is null whenever overage is not billed for your team, which includes Pay-as-you-go.
• included_credits_remaining and overage_credits are measured across your whole team, every Luma surface included, so they do not reconcile with total_credits_used.

By model

One row per model and action. action is Generate, Modify, Extend or Reframe, so one model can appear on several rows, each at its own rate.

curl -s "https://agents.lumalabs.ai/v1/usage?group_by=model" \
  -H "Authorization: Bearer $LUMA_API_KEY"

{
  "period_start": "2026-10-01T00:00:00+00:00",
  "period_end": "2026-11-01T00:00:00+00:00",
  "groups": [
    {
      "model": "uni-1",
      "action": "Generate",
      "count": 1,
      "total_credits": 14
    },
    {
      "model": "uni-1-max",
      "action": "Generate",
      "count": 1,
      "total_credits": 17
    }
  ]
}

By end user

One row per user_id you sent on POST /v1/generations. Send a stable user_id on every request you want attributed; a generation sent without one does not group under any id of yours.

curl -s "https://agents.lumalabs.ai/v1/usage?group_by=user" \
  -H "Authorization: Bearer $LUMA_API_KEY"

{
  "period_start": "2026-10-01T00:00:00+00:00",
  "period_end": "2026-11-01T00:00:00+00:00",
  "groups": [
    {
      "user_id": "advertiser-4417",
      "sessions": 1,
      "total_credits": 14
    },
    {
      "user_id": "advertiser-9001",
      "sessions": 1,
      "total_credits": 17
    }
  ]
}

By session

The 100 highest-spending sessions, most expensive first. Add user_id to keep one end user’s.

curl -s "https://agents.lumalabs.ai/v1/usage?group_by=session&user_id=advertiser-4417" \
  -H "Authorization: Bearer $LUMA_API_KEY"

{
  "period_start": "2026-10-01T00:00:00+00:00",
  "period_end": "2026-11-01T00:00:00+00:00",
  "groups": [
    {
      "session_id": "a4b8c2d6-3f1e-4a9b-8c7d-6e5f4a3b2c30",
      "total_credits": 14,
      "generation_count": 1
    }
  ]
}

By API key

One row per key, with the name and metadata you gave it. This grouping also counts spend from agent sessions opened with the key, so it can be larger than the summary.

curl -s "https://agents.lumalabs.ai/v1/usage?group_by=api_key" \
  -H "Authorization: Bearer $LUMA_API_KEY"

{
  "period_start": "2026-10-01T00:00:00+00:00",
  "period_end": "2026-11-01T00:00:00+00:00",
  "groups": [
    {
      "api_key_id": "5e55a9e0-0000-4000-8000-000000000003",
      "name": "production",
      "metadata": {
        "env": "prod"
      },
      "sessions": 5,
      "total_credits": 398
    }
  ]
}

Info

If either endpoint answers 501, usage reporting is switched off where you are calling it. Enterprise teams that need usage by subteam, project or board use the Admin API.

---

Credits and dollars

Every figure the API returns is in credits. To convert, multiply by your rate in USD per credit:

1. If GET /v1/usage returns a non-null overage_rate, that is your rate for credits past your allowance. It is a decimal string; parse it as a decimal, not a float, if you bill on it.
2. Otherwise, your plan or contract sets your rate.
3. The default list rate is $0.003 per credit: what a credit bought at list price costs. Use it only when neither of the above gives you a rate, and label it as the list rate, because a contract can differ.

dollars = credits × rate. Pricing quotes a price per generation; do not divide it by a generation’s credits to get a rate, because credits are whole numbers and the division does not come out to your rate.

---

Next steps

• Pricing — Per-generation prices and Provisioned Throughput plans
• Rate limits — Default limits and request behavior
• FAQ — Common billing questions