ElevenLabs Character Quota Sentinel for Kestra

id: elevenlabs-character-quota-sentinel
namespace: company.team
description: |
  Every few hours, read the ElevenLabs subscription of the account
  (read-only: no audio is generated and no plan is changed) and classify
  the text-to-speech character quota as HEALTHY, WARNING, CRITICAL or
  UNREACHABLE. Log quiet runs and alert Slack before voice features run
  out of characters, or when the subscription is no longer active.

inputs:
  - id: warning_used_pct
    type: FLOAT
    defaults: 80.0
    displayName: "Warning Used (%)"
    description: "At or above this share of the character limit used, the check is WARNING."
  - id: critical_used_pct
    type: FLOAT
    defaults: 95.0
    displayName: "Critical Used (%)"
    description: "At or above this share of the character limit used, the check is
      CRITICAL."

triggers:
  - id: quota_check
    type: io.kestra.plugin.core.trigger.Schedule
    description: Check the character quota every 6 hours. Shipped disabled; enable
      it once the ElevenLabs API key secret is set and a manual run has been
      verified.
    cron: "40 */6 * * *"
    disabled: true

tasks:
  - id: get_subscription
    type: io.kestra.plugin.core.http.Request
    description: Read the account's subscription, including characters used, the
      character limit and the next reset time, from the ElevenLabs API. This is
      a GET; no audio is generated.
    uri: "https://api.elevenlabs.io/v1/user/subscription"
    method: GET
    headers:
      xi-api-key: "{{ secret('ELEVENLABS_API_KEY') }}"
    options:
      allowFailed: true
      timeout:
        connectTimeout: PT10S
        readIdleTimeout: PT30S
    retry:
      type: constant
      interval: PT10S
      maxAttempts: 3
    allowFailure: true

  - id: summarize_quota
    type: io.kestra.plugin.core.debug.Return
    description: Compute the share of the character limit used, the characters left
      and the days until the quota resets, treat any subscription status other
      than active or trialing as a problem, and classify in one jq query. A
      missing or non-200 response becomes UNREACHABLE.
    format: >-
      {{ (outputs.get_subscription.code is not defined or
      outputs.get_subscription.code != 200) ?
      '{"status":"UNREACHABLE","tier":"n/a","used_pct":0,"chars_left":0,"days_to_reset":0,"subscription_status":"n/a"}'
      : (fromJson(outputs.get_subscription.body) | jq(' (.character_count // 0)
      as $used | (.character_limit // 0) as $limit | (if $limit == 0 then 100
      else (($used * 1000 / $limit) | floor) / 10 end) as $pct | (if
      .next_character_count_reset_unix == null then 0 else
      (((.next_character_count_reset_unix - ' ~ (now() | timestamp) ~ ') / 8640
      | floor) / 10) end) as $days | (.status // "unknown") as $st | {tier:
      (.tier // "unknown"), used: $used, limit: $limit, used_pct: $pct,
      chars_left: ([($limit - $used), 0] | max), days_to_reset: $days,
      subscription_status: $st, status: (if ($st != "active" and $st !=
      "trialing" and $st != "free") then "CRITICAL" elif $pct >= ' ~
      inputs.critical_used_pct ~ ' then "CRITICAL" elif $pct >= ' ~
      inputs.warning_used_pct ~ ' then "WARNING" else "HEALTHY" end)} ') | first
      | toJson) }}

  - id: route_by_quota
    type: io.kestra.plugin.core.flow.Switch
    description: Route to a quiet log when the quota is comfortable, a Slack message
      when usage crosses the warning line, or a Slack page when it crosses the
      critical line, the subscription is not active, or the API could not be
      read.
    value: "{{ fromJson(outputs.summarize_quota.value).status }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          message: "ElevenLabs quota healthy: {{
            fromJson(outputs.summarize_quota.value).used_pct }}% of {{
            fromJson(outputs.summarize_quota.value).limit }} characters used on
            the {{ fromJson(outputs.summarize_quota.value).tier }} tier, resets
            in {{ fromJson(outputs.summarize_quota.value).days_to_reset }}
            day(s)."
      "WARNING":
        - id: alert_warning_quota
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Post a Slack message when character usage is at or above the
            warning line.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "ElevenLabs quota WARNING: {{ fromJson(outputs.summarize_quota.value).used_pct }}% of characters used ({{ fromJson(outputs.summarize_quota.value).chars_left }} left) on the {{ fromJson(outputs.summarize_quota.value).tier }} tier; resets in {{ fromJson(outputs.summarize_quota.value).days_to_reset }} day(s). Plan an upgrade or slow down batch generation. Execution {{ execution.id }}."
            }
      "CRITICAL":
        - id: alert_critical_quota
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when usage is at or above the critical line or the
            subscription is not active, because voice features will stop
            working.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "ElevenLabs quota CRITICAL: {{ fromJson(outputs.summarize_quota.value).used_pct }}% used, {{ fromJson(outputs.summarize_quota.value).chars_left }} characters left, subscription status {{ fromJson(outputs.summarize_quota.value).subscription_status }}, resets in {{ fromJson(outputs.summarize_quota.value).days_to_reset }} day(s). Text-to-speech requests will start failing. Execution {{ execution.id }}."
            }
      "UNREACHABLE":
        - id: alert_unreachable_api
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when the subscription endpoint could not be read,
            indicating an outage or an invalid API key.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "ElevenLabs quota sentinel UNREACHABLE: the subscription endpoint did not return a usable response (HTTP {{ outputs.get_subscription.code ?? 'no response' }}). Check the API key. Execution {{ execution.id }}."
            }
    defaults:
      - id: log_unclassified
        type: io.kestra.plugin.core.log.Log
        message: "ElevenLabs quota sentinel completed with an unexpected classification:
          {{ outputs.summarize_quota.value }}."

  - id: log_audit_result
    type: io.kestra.plugin.core.log.Log
    description: Record one audit line for every run, whichever branch fired, so the
      quota history stays queryable even if Slack delivery fails.
    message: "ElevenLabs quota sentinel audit: http={{ outputs.get_subscription.code
      ?? 'n/a' }} summary={{ outputs.summarize_quota.value }} execution={{
      execution.id }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alert Slack when the sentinel flow itself fails, so a broken check
      is never mistaken for a comfortable quota.
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {
        "text": "ElevenLabs quota sentinel flow {{ flow.id }} FAILED (execution {{ execution.id }}). The character quota is now unknown; check the task logs and the ElevenLabs subscription page."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ fromJson(outputs.summarize_quota.value).status }}"

Voice agents, audiobook pipelines, IVR prompts and read-aloud features built on ElevenLabs all draw from one monthly character quota. When it runs out, or a payment fails and the subscription stops being active, every text-to-speech request starts failing at once, often in the middle of a batch job or a live call. ElevenLabs shows usage on its subscription page, but nothing pages the team as the quota runs down. This blueprint turns a scheduled, read-only call to the ElevenLabs API into a quota gate: io.kestra.plugin.core.http.Request reads the subscription, one jq query works out the share used, the characters left and the days until reset, and the result routes to a quiet log or a Slack alert.

How it works

get_subscription (io.kestra.plugin.core.http.Request) calls GET /v1/user/subscription with the xi-api-key header. It is a read: no audio is generated and no plan is changed. Retries cover short network blips, and allowFailed plus allowFailure keep an API error from aborting the flow so it can be reported instead.
summarize_quota (io.kestra.plugin.core.debug.Return) first guards for a missing or non-200 response (UNREACHABLE). Otherwise one jq query computes character_count / character_limit, the characters left, and the days until next_character_count_reset_unix, and reads tier and status. A subscription status other than active, trialing or free is CRITICAL; usage at or above critical_used_pct is CRITICAL; at or above warning_used_pct is WARNING; otherwise HEALTHY.
route_by_quota (io.kestra.plugin.core.flow.Switch) branches on that classification: HEALTHY logs quietly, WARNING posts a Slack note, CRITICAL and UNREACHABLE page Slack. A defaults fallback logs anything unexpected.
log_audit_result (io.kestra.plugin.core.log.Log) writes one audit line per run with the HTTP status and the full summary.
The flow-level errors block pages Slack if the flow itself fails, and the quota_check trigger runs every 6 hours, shipped disabled: true.

What you get

A read-only quota check with no custom scripting and no extra plugin to install.
A status output (HEALTHY / WARNING / CRITICAL / UNREACHABLE) other flows can gate on, for example to pause a bulk narration job or switch to a fallback voice when the quota is nearly gone.
Slack messages with the share used, the characters left, the tier and the days to reset.
An audit line on every run, separate from Slack.

Who it's for

Teams running voice agents, read-aloud accessibility features, podcasts or audiobook pipelines on ElevenLabs.
Developers running batch text-to-speech jobs in Kestra who need to know the quota will last.
Product owners who want an early warning before upgrading the plan.

Why orchestrate this with Kestra

The quota lives on a settings page and usage spikes come from your own batch jobs, often ones already running in Kestra. Kestra turns a plain, read-only API call into a scheduled, typed classification with retries, a failure path and an execution history, and the status output lets the very flows that use the quota hold back before it runs out.

Prerequisites

An ElevenLabs account (the free tier works for testing) and an API key from the profile settings.
A Slack incoming webhook for the WARNING, CRITICAL, UNREACHABLE and flow-failure alerts.

Secrets

ELEVENLABS_API_KEY: an ElevenLabs API key with permission to read the user subscription.
SLACK_WEBHOOK: Slack incoming webhook used for every alert branch and the flow-failure alert.

In Kestra OSS, secrets are supplied as environment variables prefixed SECRET_ and base64-encoded, for example SECRET_ELEVENLABS_API_KEY=$(echo -n 'sk_xxxxxxxx' | base64), and read back with {{ secret('ELEVENLABS_API_KEY') }}. Use the Enterprise secrets backend for encryption at rest and access control.

Quick start

Create an ElevenLabs API key and add ELEVENLABS_API_KEY and SLACK_WEBHOOK as secrets.
Run the flow manually and compare the share used and characters left in the logs with the subscription page.
Lower warning_used_pct below your current usage to see the WARNING path, then set it back.
Enable quota_check.

How to extend

Store each run's character_count in a KV store to compute the daily burn rate and alert when the quota will run out before the reset date.
Gate a bulk narration flow on status == HEALTHY with a Flow trigger.
Add a call to the usage endpoint to break usage down by voice or by API key.
Alert only when the status changes, using a KV store.

Inputs

warning_used_pct: type FLOAT, default 80.0.
critical_used_pct: type FLOAT, default 95.0.

Outputs

status: one of HEALTHY, WARNING, CRITICAL, UNREACHABLE.
Example path: {{ fromJson(outputs.summarize_quota.value).chars_left }} for the characters left this period.

Pitfalls

Plans with usage-based billing can go past the character limit and charge for the extra; treat CRITICAL as "expensive from now on" rather than "stopped" in that case.
Days to reset are computed from next_character_count_reset_unix against the Kestra server clock in UTC.
The set of subscription status values that count as healthy (active, trialing, free) is a judgement call; add others if your plan reports a different value while working normally.
This flow only reads; it never generates audio or changes the plan.