Retrieve a plan | Runledger API

{
  "id": "plan_8hJ2kL5zXc",
  "object": "string",
  "key": "enterprise_monthly",
  "name": "string",
  "status": "active",
  "billing_mode": "prepaid",
  "currency": "string",
  "interval": "month",
  "rates": [
    {
      "event_name": "agent.task",
      "outcome_definition": "chat_resolution",
      "credits_per_unit": "10",
      "unit_amount_decimal": "95",
      "price_rule": "video_cost_plus",
      "included_quantity": "1000",
      "overage_unit_amount_decimal": "120",
      "burn_multiplier": "1",
      "description": "Chat resolutions"
    }
  ],
  "has_subscriptions": true,
  "metadata": {},
  "livemode": true,
  "created_at": "2024-01-15T09:30:00Z",
  "description": "string",
  "credit_type": "string",
  "recurring_fee": {
    "amount": 1500,
    "currency": "usd"
  },
  "included_credits": {
    "amount": "5000",
    "pool": "included",
    "rollover": "none",
    "rollover_cap": "2000"
  },
  "top_up": {
    "unit_amount_decimal": "1",
    "minimum_credits": "1000",
    "maximum_credits": "1000000",
    "pool": "purchased",
    "credits_expire_in": "P1Y",
    "low_balance_at": "1000",
    "auto": {
      "allowed": false,
      "maximum_monthly_limit": {
        "amount": 1500,
        "currency": "usd"
      }
    }
  },
  "allowances": [
    {
      "key": "weekly",
      "kind": "refill",
      "amount": "1500",
      "window": {
        "type": "fixed",
        "duration": "P1W",
        "anchor": "billing_period"
      },
      "pool": "included",
      "scope": "customer",
      "rollover": "none",
      "rollover_cap": "500",
      "rollover_expires_after": "P1M",
      "priority": 50,
      "on_exhausted": "block",
      "alert_at": [
        "0.8",
        "1"
      ]
    }
  ],
  "pools": [
    {
      "key": "included",
      "name": "Included usage",
      "burn_multiplier": "1"
    }
  ],
  "per_seat": true,
  "default_spend_limit": {
    "amount": {
      "amount": 1500,
      "currency": "usd"
    },
    "ceiling": {
      "amount": 1500,
      "currency": "usd"
    },
    "period": {
      "duration": "P1M",
      "anchor": "calendar"
    },
    "counts": "paid_usage",
    "action": "warn",
    "alert_at": [
      "0.75",
      "0.9",
      "1"
    ]
  },
  "overdraft_limit": "string",
  "credit_limit": {
    "amount": 1500,
    "currency": "usd"
  },
  "minimum_commitment": {
    "amount": 1500,
    "currency": "usd"
  },
  "invoice_grace_period": "string",
  "actor": {
    "type": "user",
    "id": "usr_4tN8vB2cXk",
    "name": "Claude Code",
    "on_behalf_of": "usr_4tN8vB2cXk",
    "client": "claude-code"
  }
}

Authentication

AuthorizationBearer

A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.

Path parameters

planstringRequired

The plan ID (plan_...) or key.

Response

The plan.

idstring

object"plan"

keystring

namestring

statusenum

Allowed values:

billing_modeenum

prepaid: a credit balance that must cover charges, topped up or granted in advance. postpaid: charges accrue in money and are invoiced at period end.

Allowed values:

currencystring

intervalenum

Allowed values:

rateslist of objects

has_subscriptionsboolean

Once true, pricing can't change.

metadatamap from strings to strings

Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.

livemodeboolean

created_atdatetime

descriptionstringOptional

credit_typestringOptional

recurring_feeobjectOptional

An amount of money in the currency's minor unit.

included_creditsobjectOptional

Prepaid. Credits granted at the start of each period.

top_upobjectOptional

Prepaid. Lets customers buy more credits through checkout.

allowanceslist of objectsOptional

Refills and caps on the plan’s balance. See Usage windows.

poolslist of objectsOptional

Named balance pools, in drawdown order. See Pools.

per_seatbooleanOptional

recurring_fee and included_credits are per seat, multiplied by the subscription’s quantity. Default false.

default_spend_limitobjectOptional

The spend limit each new subscription on the plan starts with. A customer-set limit may replace it, up to ceiling.

overdraft_limitstringOptional

credit_limitobjectOptional

An amount of money in the currency's minor unit.

minimum_commitmentobjectOptional

An amount of money in the currency's minor unit.

invoice_grace_periodstringOptional

actorobjectOptional

Who last changed the plan.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error