Usage and requests

Usage

GET https://api.scenema.ai/v1/usage returns this month’s API usage, in credits:

{
  "periodStart": "2026-10-01T00:00:00.000Z",
  "credits": { "used": 18420, "held": 1200, "balance": 9380 },
  "requests": { "total": 342, "errors": 6 }
}

Field	Meaning
credits.used	Credits charged this month for finished narrations and videos.
credits.held	Credits held now for narrations and videos still running.
credits.balance	Credits available to spend.
requests	Requests logged this month (see below), and how many failed.

The request log

GET https://api.scenema.ai/v1/requests lists the workspace’s requests, newest first, with page and perPage (up to 100). Filter with status (success or error), route (for example /v1/videos), since and until (ISO 8601).

The log keeps every request that created or changed something (a narration, a video, an upload, a webhook retry) and every request that failed, for 30 days. A successful read is kept at most once every 5 minutes for each path: a video is polled for minutes, and every poll would bury the requests that matter.

Field	Meaning
route, path, method	The endpoint, and the path as called.
statusCode, durationMs	What Scenema answered, and how long it took.
subjectId	The narration, video or asset it created or read.
credits	For the request that created a narration or video: held, used and returned.
webhook	delivered, pending or failed, when it asked for one.

GET https://api.scenema.ai/v1/requests/{id} adds what was sent (requestBody) and what Scenema answered right away (responseBody), and every webhook delivery of what it created, each with the body it sent (payload, the finished narration or video) and its attempts. Long values are trimmed, values that look like secrets are removed, and an uploaded file is shown as its name, type and size.