OpenRouter Credit Runway Sentinel for Kestra

id: openrouter-credit-runway-sentinel
namespace: company.team
description: |
  Every few hours, read the OpenRouter account credits (read-only: no model
  is called and nothing is purchased) and classify the remaining balance as
  HEALTHY, WARNING, CRITICAL or UNREACHABLE. Log quiet runs and alert Slack
  before LLM-powered agents and flows stop working because the prepaid
  credits ran out.

inputs:
  - id: warning_remaining_usd
    type: FLOAT
    defaults: 20.0
    displayName: "Warning Remaining (USD)"
    description: "At or below this remaining credit balance, the check is WARNING."
  - id: critical_remaining_usd
    type: FLOAT
    defaults: 5.0
    displayName: "Critical Remaining (USD)"
    description: "At or below this remaining credit balance, the check is CRITICAL."

triggers:
  - id: credit_check
    type: io.kestra.plugin.core.trigger.Schedule
    description: Check the credit balance every 3 hours. Shipped disabled; enable it
      once the OpenRouter management key secret is set and a manual run has been
      verified.
    cron: "50 */3 * * *"
    disabled: true

tasks:
  - id: get_credits
    type: io.kestra.plugin.core.http.Request
    description: Read total credits purchased and total credits used from the
      OpenRouter credits endpoint. This is a GET with a management key; no model
      is called and nothing is bought.
    uri: "https://openrouter.ai/api/v1/credits"
    method: GET
    headers:
      Authorization: "Bearer {{ secret('OPENROUTER_MANAGEMENT_KEY') }}"
    options:
      allowFailed: true
      timeout:
        connectTimeout: PT10S
        readIdleTimeout: PT30S
    retry:
      type: constant
      interval: PT10S
      maxAttempts: 3
    allowFailure: true

  - id: summarize_credits
    type: io.kestra.plugin.core.debug.Return
    description: Compute the remaining balance and the share of purchased credits
      already used, and classify in one jq query. A missing or non-200 response
      (including 403 for a non-management key) becomes UNREACHABLE instead of
      looking healthy.
    format: >-
      {{ (outputs.get_credits.code is not defined or outputs.get_credits.code !=
      200) ?
      '{"status":"UNREACHABLE","total_credits":0,"total_usage":0,"remaining":0,"used_pct":0}'
      : (fromJson(outputs.get_credits.body) | jq(' (.data.total_credits // 0) as
      $c | (.data.total_usage // 0) as $u | ((($c - $u) * 100 | round) / 100) as
      $rem | {total_credits: $c, total_usage: (($u * 100 | round) / 100),
      remaining: $rem, used_pct: (if $c == 0 then 100 else (($u * 1000 / $c) |
      floor) / 10 end), status: (if $rem <= ' ~ inputs.critical_remaining_usd ~
      ' then "CRITICAL" elif $rem <= ' ~ inputs.warning_remaining_usd ~ ' then
      "WARNING" else "HEALTHY" end)} ') | first | toJson) }}

  - id: route_by_credits
    type: io.kestra.plugin.core.flow.Switch
    description: Route to a quiet log when the balance is comfortable, a Slack
      message when it drops to the warning line, or a Slack page when it drops
      to the critical line or the credits could not be read.
    value: "{{ fromJson(outputs.summarize_credits.value).status }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          message: "OpenRouter credits healthy: {{
            fromJson(outputs.summarize_credits.value).remaining }} USD left of
            {{ fromJson(outputs.summarize_credits.value).total_credits }}
            purchased ({{ fromJson(outputs.summarize_credits.value).used_pct }}%
            used)."
      "WARNING":
        - id: alert_warning_credits
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Post a Slack message when the remaining balance is at or below the
            warning line.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "OpenRouter credits WARNING: {{ fromJson(outputs.summarize_credits.value).remaining }} USD left ({{ fromJson(outputs.summarize_credits.value).used_pct }}% of {{ fromJson(outputs.summarize_credits.value).total_credits }} USD used). Top up or turn on auto top-up before LLM calls start failing. Execution {{ execution.id }}."
            }
      "CRITICAL":
        - id: alert_critical_credits
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when the remaining balance is at or below the critical
            line, because every flow and agent calling OpenRouter will soon get
            payment-required errors.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "OpenRouter credits CRITICAL: only {{ fromJson(outputs.summarize_credits.value).remaining }} USD left. Agents and flows calling OpenRouter will start failing with payment errors; top up now. Execution {{ execution.id }}."
            }
      "UNREACHABLE":
        - id: alert_unreachable_api
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when the credits endpoint could not be read, for example
            an outage or a key that is not a management key (HTTP 403).
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "OpenRouter credit sentinel UNREACHABLE: the credits endpoint did not return a usable response (HTTP {{ outputs.get_credits.code ?? 'no response' }}). The credits endpoint needs a management key, not an inference key. Execution {{ execution.id }}."
            }
    defaults:
      - id: log_unclassified
        type: io.kestra.plugin.core.log.Log
        message: "OpenRouter credit sentinel completed with an unexpected
          classification: {{ outputs.summarize_credits.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
      credit history stays queryable even if Slack delivery fails.
    message: "OpenRouter credit sentinel audit: http={{ outputs.get_credits.code ??
      'n/a' }} summary={{ outputs.summarize_credits.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 balance.
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {
        "text": "OpenRouter credit sentinel flow {{ flow.id }} FAILED (execution {{ execution.id }}). The credit balance is now unknown; check the task logs and the OpenRouter credits page."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ fromJson(outputs.summarize_credits.value).status }}"
  - id: remaining_usd
    type: STRING
    value: "{{ fromJson(outputs.summarize_credits.value).remaining }}"

Many agents, RAG pipelines and AI flows reach dozens of models through OpenRouter on prepaid credits. When the balance hits zero, every call returns a payment-required error at once: the support bot stops answering, the nightly summarization job fails, and the first sign is a wave of errors. OpenRouter shows the balance on its credits page, but nothing pages the team as it runs down. This blueprint turns a scheduled, read-only call to the OpenRouter credits endpoint into a spend gate: io.kestra.plugin.core.http.Request reads credits purchased and used, one jq query works out the remaining balance, and the result routes to a quiet log or a Slack alert.

How it works

get_credits (io.kestra.plugin.core.http.Request) calls GET /api/v1/credits with a bearer management key. It is a read: no model is called and nothing is purchased. Retries cover short network blips, and allowFailed plus allowFailure keep an API error from aborting the flow so it can be reported instead.
summarize_credits (io.kestra.plugin.core.debug.Return) first guards for a missing or non-200 response (UNREACHABLE; OpenRouter answers 403 if the key is not a management key). Otherwise one jq query computes data.total_credits - data.total_usage and the share used, and classifies: a remaining balance at or below critical_remaining_usd is CRITICAL, at or below warning_remaining_usd is WARNING, otherwise HEALTHY.
route_by_credits (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 credit_check trigger runs every 3 hours, shipped disabled: true.

What you get

A read-only credit check with no custom scripting and no extra plugin to install.
status and remaining_usd outputs other flows can gate on, for example to pause expensive batch jobs or switch an agent to a cheaper model when credits are low.
Slack messages with the remaining balance and the share used.
An audit line on every run, separate from Slack, which doubles as a spend history.

Who it's for

Teams running agents, chatbots and AI flows through OpenRouter on prepaid credits.
Solo builders and small startups who cannot afford their product going silent because a balance hit zero.
Kestra users whose own AI flows call OpenRouter and want the guard next to them.

Why orchestrate this with Kestra

The flows that spend the credits often already run 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 remaining_usd output lets those same flows throttle themselves before the balance runs out.

Prerequisites

An OpenRouter account with purchased credits.
A management key (created under Settings > Management Keys); ordinary inference keys get HTTP 403 on the credits endpoint.
A Slack incoming webhook for the WARNING, CRITICAL, UNREACHABLE and flow-failure alerts.

Secrets

OPENROUTER_MANAGEMENT_KEY: an OpenRouter management key.
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_OPENROUTER_MANAGEMENT_KEY=$(echo -n 'sk-or-v1-xxxxxxxx' | base64), and read back with {{ secret('OPENROUTER_MANAGEMENT_KEY') }}. Use the Enterprise secrets backend for encryption at rest and access control.

Quick start

Create a management key in OpenRouter and add OPENROUTER_MANAGEMENT_KEY and SLACK_WEBHOOK as secrets.
Run the flow manually and compare remaining_usd with the balance on the OpenRouter credits page.
Raise warning_remaining_usd above your current balance to see the WARNING path, then set it back.
Enable credit_check.

How to extend

Store each run's total_usage in a KV store to compute the daily burn and alert when the balance will run out within N days, not only when it is low.
Gate expensive batch flows on status == HEALTHY with a Flow trigger.
List per-key usage with OpenRouter's key-management endpoints to find which app is spending the most.
Alert only on status changes, using a KV store.

Inputs

warning_remaining_usd: type FLOAT, default 20.0.
critical_remaining_usd: type FLOAT, default 5.0.

Outputs

status: one of HEALTHY, WARNING, CRITICAL, UNREACHABLE.
remaining_usd: remaining credit balance in USD.

Pitfalls

The credits endpoint needs a management key; an inference key returns 403 and the run is reported as UNREACHABLE with that hint.
Balances are account-wide; per-key spending limits are separate and are not checked here.
Usage can lag a little behind very recent requests, so treat the balance as approximate during heavy bursts.
This flow only reads; it never calls a model or buys credits.