Usage API

Read your monthly request allowance and recent activity over HTTP: the same numbers and list as the Usage page in the console. Use it to check what’s left before sending, show remaining requests in your own app, cut back low-priority announcements near the limit, or check your own count against Voice Monkey’s.

Calling /usage doesn’t use a request.

Endpoint

GET/POST https://api-v3.voicemonkey.io/usage

curl https://api-v3.voicemonkey.io/usage \
  -H "Authorization: Bearer YOUR_TOKEN"

Or with the token as a query parameter:

curl "https://api-v3.voicemonkey.io/usage?token=YOUR_TOKEN"

Parameters

Parameter	Required	Description
`token`	yes	Your API token. Or send it via the `Authorization: Bearer …` header. See Authentication.

Response

Successful calls return 200:

{
  "success": true,
  "data": {
    "plan": "hobby",
    "used": 9,
    "limit": 15000,
    "remaining": 14991,
    "periodStart": "2026-10-07T00:00:00.000Z",
    "periodEnd": "2026-11-07T00:00:00.000Z",
    "history": [
      {
        "at": "2026-10-20T19:58:12.345Z",
        "type": "announcement",
        "device": "kitchen-echo-show-3f7k2",
        "deviceName": "Kitchen Echo Show",
        "source": "flow",
        "ok": true,
        "counted": true,
        "flow": "4821",
        "flowName": "Service status"
      },
      {
        "at": "2026-10-20T19:40:03.120Z",
        "type": "routine",
        "device": "porch-lights-x4n8e",
        "deviceName": "Porch lights",
        "source": "api",
        "ok": false,
        "counted": true,
        "error": "ALEXA_TRIGGER_FAILED"
      }
    ]
  }
}

Field	Description
`plan`	Plan key, as returned by `/me`.
`used`	Requests used in the current period.
`limit`	Your plan’s requests per period. `null` on unlimited plans.
`remaining`	`limit` minus `used`, never below `0`. `null` on unlimited plans.
`periodStart` / `periodEnd`	When the current period started and when it resets, as UTC timestamps. The period runs monthly from your billing date.
`history`	Recent announcements and routine triggers, newest first. See below.

What counts as a request

Each time Voice Monkey sends an announcement or a routine trigger to Alexa, that’s one request. A Flow uses one each time it fires a Routine and each time it sends speech, sound or a visual to a Speaker. Reminders use one per Speaker each time they play. Reading endpoints such as /usage, /me, /devices, /flows and GET /variables don’t count.

History entries

history lists one entry per announcement or routine trigger. Your plan keeps the most recent ones: 10 on Free and the legacy plans, 50 on Hobby and 100 on Ultimate. Clearing activity on the console’s Usage page clears this list too; it doesn’t reset used.

Field	Description
`at`	When it was sent (UTC).
`type`	`announcement` (a Speaker) or `routine` (a Routine Trigger).
`device`	The device ID, as passed to `/announce` and `/trigger`.
`deviceName`	The device’s current name, or `null` if it has since been deleted.
`source`	What started it: `api` (`/announce` or `/trigger`, including Zapier, Home Assistant and AI assistants), `flow` (a Flow run, from `/flow`, the console, a voice command or another Flow), `schedule` (a scheduled Flow), `webhook` (an inbound webhook), `reminder` (a reminder or its countdown), `screen` (a button tapped on a Screen) or `console` (sent from the console, e.g. a Screen’s Send button).
`ok`	`true` if Alexa accepted it.
`counted`	Whether it used a request. Only requests turned away before reaching Alexa (`THROTTLED`, `MONTHLY_QUOTA_EXCEEDED`) don’t count; a failed call that reached Alexa still does.
`error`	Only when `ok` is `false`: `THROTTLED`, `MONTHLY_QUOTA_EXCEEDED` or `ALEXA_TRIGGER_FAILED`, the same codes `/announce` returns. The console’s Usage page shows more detail.
`flow` / `flowName`	Only for Flow runs: the Flow’s request reference (what you pass as `flow` to `/flow`) and its name at the time. Older entries may have `flowName` only.
`scheduleName` / `webhookName` / `reminderName`	Only when a schedule, inbound webhook or reminder started it: its name at the time.

history is [] until something has been sent.

Errors

Status	Response body	Meaning
`401`	`{ "error": "UNAUTHORIZED" }`	No token supplied.
`401`	`{ "error": "INVALID_TOKEN" }`	Token doesn’t match an active token.
`429`	`{ "error": "THROTTLED", "lockoutUntil": "<ISO>" }`	Per-user safety lockout. Back off until the timestamp.

Tips

To pace announcements across the month, compare remaining with the time left until periodEnd rather than waiting for MONTHLY_QUOTA_EXCEEDED.
In Flows, Screens and announcements, {VM.USAGE.REMAINING} gives the same remaining number without an API call.