--- title: Usage and credits | Luma Agents description: Read your credit balance and what you spent with GET /v1/credits and GET /v1/usage, and convert credits to dollars. --- 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 ```bash curl -s "https://agents.lumalabs.ai/v1/credits" \ -H "Authorization: Bearer $LUMA_API_KEY" ``` ```json { "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](#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 ```bash curl -s "https://agents.lumalabs.ai/v1/usage" \ -H "Authorization: Bearer $LUMA_API_KEY" ``` ```json { "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. ```bash curl -s "https://agents.lumalabs.ai/v1/usage?group_by=model" \ -H "Authorization: Bearer $LUMA_API_KEY" ``` ```json { "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. ```bash curl -s "https://agents.lumalabs.ai/v1/usage?group_by=user" \ -H "Authorization: Bearer $LUMA_API_KEY" ``` ```json { "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. ```bash curl -s "https://agents.lumalabs.ai/v1/usage?group_by=session&user_id=advertiser-4417" \ -H "Authorization: Bearer $LUMA_API_KEY" ``` ```json { "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. ```bash curl -s "https://agents.lumalabs.ai/v1/usage?group_by=api_key" \ -H "Authorization: Bearer $LUMA_API_KEY" ``` ```json { "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 } ] } ``` 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](/admin-api/team/usage-breakdown/index.md). --- ## 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](/guides/pricing/index.md) 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**](/guides/pricing/index.md) — Per-generation prices and Provisioned Throughput plans - [**Rate limits**](/guides/rate-limits/index.md) — Default limits and request behavior - [**FAQ**](/guides/faq/index.md) — Common billing questions