See metered use over a period
GET /v1/usage
Returns your use by product, as billed. Without dates it covers the current month, in UTC, to now. Called with a test key, it returns the account's test use instead.
Authentication
Send Authorization: Bearer $KEY from your server. Create or rotate keys.
Example request
bash
curl 'https://play.fellowverse.app/v1/usage?from=2026-10-01&to=2026-11-01' \
-H "Authorization: Bearer $KEY"
Example IDs are placeholders. Use the upload or job ID returned by your own request.
Parameters
| Name | In | Required | Type | Description and constraints |
|---|---|---|---|---|
from |
query | No | string | The start of the period, included. An ISO date or time. |
to |
query | No | string | The end of the period, left out. An ISO date or time. Now when not given. |
Responses
| Status | Meaning |
|---|---|
| 200 | Use in the period. |
| 400 | The request could not be used. invalid_request when a field is missing or has the wrong type; bad_request when the audio or a value could not be read. |
| 401 | The key is missing, wrong, revoked, or past the end of its grace period after a roll. The code is api_unauthorized, and the reason says which. |
| 403 | The account is suspended (api_suspended), or a live key was used on an account that has test keys only (api_live_locked). |
| 500 | Something went wrong on our side. The code is internal. |
200: application/json
| Field | Type | Required | Description and constraints |
|---|---|---|---|
from |
string | Yes | Format: date-time. |
to |
string | Yes | Format: date-time. |
livemode |
boolean | Yes | True for a live key's billed use; false for a test key's free use. |
usage |
object[] | Yes | |
usage[].product |
string | Yes | One of search, voice_search, alignment. |
usage[].unit |
string | Yes | One of request, audio_second. |
usage[].units |
number | Yes | The billed amount, to two decimal places. |
usage[].events |
integer | Yes | How many billable calls or jobs. |
“Required” is relative to the containing object. Optional success results and failure errors depend on the job state.
Errors and limits
JSON errors contain error.code, error.problem, error.reason and error.fix. Handle errors and retries and check test and live limits.
Need the contract? Download OpenAPI. Manage keys and account access in the developer console.