Usage

Minutes, period and limits for the key's account.

Operations

GET Minutes, period and limits for this account

GET /v1/usage

Read limits.perFileMinutes before a long upload; minutes.remaining is what a job may still cost (plan allowance plus purchased credit).

Responses

Status	Meaning	Body
200	The account's usage.	Usage
401	The API key is missing, malformed, unknown, revoked, expired, or for the other environment (invalid-api-key).	Problem
429	Over 120 requests/minute for this key (rate-limited). Honour Retry-After.	Problem
500	Usage could not be read (internal).	Problem

curl

curl "https://api.esfera.audio/v1/usage" \
  -H "Authorization: Bearer $ESFERA_API_KEY"

Node.js

import { Esfera } from "@esfera/sdk";

const esfera = new Esfera({ apiKey: process.env.ESFERA_API_KEY });

const usage = await esfera.usage.get();

Python

import os
import requests

res = requests.get(
    "https://api.esfera.audio/v1/usage",
    headers={
        "Authorization": f"Bearer {os.environ['ESFERA_API_KEY']}",
    },
)
res.raise_for_status()
print(res.json())

Response · 200

{
  "plan": "pro",
  "period": {
    "resetsMonthly": true,
    "resetsAt": "2026-10-01T00:00:00Z"
  },
  "minutes": {
    "used": 140,
    "included": 600,
    "remaining": 460,
    "planRemaining": 460,
    "credit": 0
  },
  "limits": {
    "perFileMinutes": 180,
    "perFileBytes": 107374182400,
    "concurrent": 1,
    "inFlight": 0,
    "rateLimitPerMinute": 120,
    "retentionHours": 72
  }
}

Objects

Usage

Field	Type	Required	Description
plan	free | creator | pro	yes	The account's plan.
period	object	yes
minutes	object	yes
limits	object	yes

Usage.period

Field	Type	Required	Description
resetsMonthly	boolean	yes	Whether the allowance refills every month.
resetsAt	string or null	yes	First instant of next month (UTC) when the allowance refills; null for a one-time grant.

Usage.minutes

Field	Type	Required	Description
used	integer	yes	Minutes used this period.
included	integer	yes	Minutes the plan includes.
remaining	integer	yes	What a job may still cost: plan remaining plus purchased credit.
planRemaining	integer	yes	Plan minutes left.
credit	integer	yes	Purchased credit minutes left.

Usage.limits

Field	Type	Required	Description
perFileMinutes	integer	yes	Longest source accepted, in minutes.
perFileBytes	integer	yes	Largest source accepted, in bytes.
concurrent	integer	yes	Conversions the account may run at once.
inFlight	integer	yes	Conversions currently holding one of concurrent slots (uploading, analysing, analysed, queued or running). inFlight < concurrent means a create will not hit concurrency-limit.
rateLimitPerMinute	integer	yes	Requests per minute for each key.
retentionHours	integer	yes	Hours an output stays available after the conversion is ready.