Credit and billing

Conversations are paid for in credits, from your organization's balance. Reading it needs billing:read. It is the same balance and the same history as the console's Billing page.

The balance

#!/bin/sh
# Read the credit balance
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/billing/balance" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

• balance is the credit on the account, and free_left how much of it is free credit not yet spent.
• available is what can still be spent: the balance, less what conversations in progress are holding, plus any credit line.
• spent_this_month counts from since, the first of the month in UTC.
• suspended is true while new conversations are refused until credit is added, and unlimited is true when the organization is never refused. enforced says whether running out stops conversations at all: when it is false, credit is counted and nothing is refused.

The balance is the organization's, whichever key reads it.

The credit history

#!/bin/sh
# List what was charged
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/billing/transactions?limit=20" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

Every movement of credit, newest first: each conversation's charge, each analysis, credit added and refunds. amount is negative when credit was spent and positive when it was added, and balance_after is the balance it left. Filter by conversation_id, by kind (repeat it for several) or by created_after, and page with next_cursor as everywhere else. Amounts are in credits, to six decimal places.

A chat is charged as it goes, so one chat can have several charges. For one conversation's total, ask for the conversation with include=cost.

The history outlives what it charged for: a deleted conversation's charges stay, under its id.

What a key sees

• A key limited to some projects reads their charges alone. Credit added to the organization belongs to no project, so it is not in that key's history.
• A test key reads what test keys spent: their chats, which use the agent's real model and are charged like any chat. Test calls cost nothing. livemode on each transaction says which kind of key it was.
• Another organization's history is never reachable, whatever the key.