Skip to content
Lumean API
GET/usage/{service}

Get Usage for Service

Same as GET /usage, narrowed to one service: consumption, remaining allowance and the reset date.

billing.read

Handy as a pre-flight check before a large job. An unknown or unavailable service code returns 404.

Required key permission: billing.read.

On this page(3)

Parameters

The inputs live inside the request line: fill in a value and you get a ready URL. Below are the type, whether it is required and the allowed values of every parameter.

GEThttps://api.lumean.app/api/public/usage/
  • stringin pathrequired

    Service code — a short latin string rather than a number. The current set is:

    CodeWhat it is
    elevenlabsText-to-speech on the ElevenLabs engine
    heygenText-to-speech on the HeyGen engine
    cartesiaText-to-speech on the Cartesia engine
    fishaudioText-to-speech on the Fish Audio engine
    lumimgImage generation
    sfxSound effects
    musicMusic tracks
    voice_searchFinding similar voices from an audio clip you upload

    Where to get the ones for your account: GET /usage returns a service_code for every service available to you — exactly the values this path accepts. The same code sits in a template’s service_key field.

    The list is open-ended: connecting a new service adds new codes, so do not hard-code the table above. An unknown code, or one you have no access to, yields 404.

    The value goes straight into the request line above.

Possible responses

200

Success. The payload is in data.

Body example
{
  "success": true,
  "message": "Success",
  "data": [
    {
      "limit_id": 12,
      "service_id": 3,
      "service_code": "elevenlabs",
      "service_name": "ElevenLabs TTS",
      "entitlement_id": 2,
      "entitlement_code": "elevenlabs_tts",
      "limit_type": "monthly",
      "limit_value": 500000,
      "used": 128400,
      "remaining": 371600,
      "period_start": "2026-07-01T00:00:00+00:00",
      "period_end": "2026-08-01T00:00:00+00:00",
      "resets_in": "2 weeks from now",
      "token_unlimited": false
    }
  ]
}
Response fields
successrequired

Success flag. Branch on the HTTP status code instead: any 2xx response carries true here, while an error comes back in a different shape that need not contain this field at all.

boolean
messagerequired

A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code.

string
datarequired

Limits for a single service — the same records as in GET /usage, filtered down. Usually one or two.

array<object>
array item
limit_idrequired

Identifier of the limit record.

integer
service_idrequired

ID of the service the limit applies to. null for limits not tied to a service.

nullable
integer
service_coderequired

Service code — the value for the GET /usage/{service} path and for a template’s service_key.

nullable
string
service_namerequired

Service name for display, in the account language.

nullable
string
entitlement_idrequired

ID of the subscription entitlement that granted this limit.

nullable
integer
entitlement_coderequired

Code of the subscription entitlement that granted the limit.

nullable
string
limit_typerequired

What exactly is being capped. Two fundamentally different things:

  • a periodic quota — consumption over a period, reset at period_end;
  • concurrent-task slots — freed on their own as soon as your running orders finish.

Exhausting the first means waiting for the period to end; the second, minutes.

string
limit_valuerequired

The ceiling under the current subscription. null means there is no ceiling (see token_unlimited).

nullable
integer
usedrequired

How much has been consumed in the current period.

integer
remainingrequired

How much is left. null when unlimited.

nullable
integer
period_startrequired

Start of the current accounting period, ISO 8601. null while no accounting period is open yet (used is then 0): the limit was never touched, or was consumed only in past periods — a period opens with the first consumption, not by the calendar.

nullable
string
period_endrequired

End of the current accounting period, ISO 8601 — the counter resets at that moment. null wherever period_start is null (no period open yet) and for limits without a period (concurrent, total).

nullable
string
resets_inrequired

Time left until the counter resets, in human-readable form. null whenever period_end is null.

nullable
string
token_unlimitedrequired

true means tokens for this service are unlimited. It does not lift the cap on concurrent tasks.

boolean
is_exceededrequired

The limit is exhausted: the next order for this service is rejected until the counter resets or a slot frees up.

boolean
usage_percentagerequired

Share consumed, 0–100. Always 0 when unlimited.

number
401

The key is missing, unknown, disabled or expired.

Analyse this response
Body example
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

Error text in the key's language (set through the X-Locale header).

string
datarequired

Always null when the request is rejected before processing.

nullable
null
403

The key lacks the required permission, or the object belongs to another user.

Analyse this response
Body example
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

Error text in the key's language (set through the X-Locale header).

string
404

Not found, or not reachable with this key.

Analyse this response
Body example
{
  "success": false,
  "message": "Resource not found."
}
Response fields
messagerequired

Error overview.

string

Nearby

Neighbouring operations

Feed this page to an AI

Open .mdllm.md

spec 0.0.1