Balance

Reference for GET /v1/balance: read the remaining balance of your account with an API key, so scripts can stop before requests fail.

Returns the balance of the account that owns the API key, so automated jobs can check funds before they send work.

GET https://usemodellane.com/v1/balance

Use this endpoint to stop a batch job before requests start failing with 402 insufficient_balance. It is not billed.

Amounts are integer strings in units of 10^-12 USD, the precision the API bills in, so they can be added and compared without rounding. Divide by 10^12 to get dollars, or read balance_usd for display.

Before a request starts, the API reserves its maximum possible cost. The reservation is released when the request finishes and only the actual usage is charged. The available amount is the total minus what running requests have reserved, and it is what a new request can use.

Request

This endpoint takes no parameters and no body. Send your API key in the Authorization header as a bearer token.

Examples

curl

curl https://usemodellane.com/v1/balance \
  -H "Authorization: Bearer $MODELLANE_API_KEY"

Python

import os
import requests

response = requests.get(
    "https://usemodellane.com/v1/balance",
    headers={"Authorization": f"Bearer {os.environ['MODELLANE_API_KEY']}"},
)
balance = response.json()
print(balance["balance_usd"])

Node.js

const response = await fetch("https://usemodellane.com/v1/balance", {
  headers: { Authorization: `Bearer ${process.env.MODELLANE_API_KEY}` },
})
const balance = await response.json()
console.log(balance.balance_usd)

Response

object string required
Possible values: balance
The object type.
currency string required
Possible values: USD
The currency of every amount in the response.
balance_pico_usd string required
The spendable total: top-up balance plus any active plan balance. An integer string in units of 10^-12 USD (divide by 10^12 for dollars).
balance_usd string required
The same total in dollars as a decimal string, for display.
reserved_pico_usd string required
The amount held for requests that are still running. An integer string in units of 10^-12 USD (divide by 10^12 for dollars).
available_pico_usd string required
What a new request can use: the total minus the reserved amount. An integer string in units of 10^-12 USD (divide by 10^12 for dollars).
topup_balance_pico_usd string required
The part of the balance that came from top-ups. It does not expire. An integer string in units of 10^-12 USD (divide by 10^12 for dollars).
plan_balance_pico_usd string required
The part that came from a monthly plan; "0" when no plan is active. An integer string in units of 10^-12 USD (divide by 10^12 for dollars).
plan_expires_at string | null required
When the plan balance expires (ISO 8601), or null without an active plan.

200

{
  "object": "balance",
  "currency": "USD",
  "balance_pico_usd": "12500000000000",
  "balance_usd": "12.5",
  "reserved_pico_usd": "40000000000",
  "available_pico_usd": "12460000000000",
  "topup_balance_pico_usd": "12500000000000",
  "plan_balance_pico_usd": "0",
  "plan_expires_at": null
}