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 }}"