Check credit usage from the API

API credit usage: the balance change log and credit totals endpoints

Two endpoints report how your account spends credits. Use them for usage dashboards, spend alerts or reconciling a batch job. To buy credits, use Manage subscription.

You want	Endpoint	Query parameters
Every balance change, with type, amount and description	Credit balance change log	`date_created_start`, `date_created_end`, `page`
Total credits spent in a period	Credit consumption totals	`date_created_start`, `date_created_end`

Total spent this month

curl "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/subscriptions/balance_change_logs/totals/?date_created_start=2026-10-01T00:00:00Z&date_created_end=2026-11-01T00:00:00Z" \
  -H "X-API-KEY: $FORAGER_API_KEY"

import os, requests

resp = requests.get(
    f"https://api-v2.forager.ai/api/{os.environ['FORAGER_ACCOUNT_ID']}/subscriptions/balance_change_logs/totals/",
    headers={"X-API-KEY": os.environ["FORAGER_API_KEY"]},
    params={"date_created_start": "2026-10-01T00:00:00Z", "date_created_end": "2026-11-01T00:00:00Z"},
)
print(resp.json()["total_credits_spent"])

const url = new URL(
  `https://api-v2.forager.ai/api/${process.env.FORAGER_ACCOUNT_ID}/subscriptions/balance_change_logs/totals/`,
);
url.search = new URLSearchParams({
  date_created_start: "2026-10-01T00:00:00Z",
  date_created_end: "2026-11-01T00:00:00Z",
});
const resp = await fetch(url, { headers: { "X-API-KEY": process.env.FORAGER_API_KEY } });
console.log((await resp.json()).total_credits_spent);

The API reference types date_created_start and date_created_end as date-times, so send full ISO 8601 timestamps such as 2026-10-01T00:00:00Z. The response has one field, total_credits_spent, returned as a string.

List balance changes

The change log is paginated. Each response has count, next, previous and results. Each result has id, change_type, change_sum, change_description and date_created. next and previous are page numbers (or null). Request page 1, 2, … until next is null.

Python

import os, requests

url = f"https://api-v2.forager.ai/api/{os.environ['FORAGER_ACCOUNT_ID']}/subscriptions/balance_change_logs/"
page = 1
while True:
    resp = requests.get(url, headers={"X-API-KEY": os.environ["FORAGER_API_KEY"]},
                        params={"date_created_start": "2026-10-01T00:00:00Z", "page": page})
    data = resp.json()
    for change in data["results"]:
        print(change["date_created"], change["change_type"], change["change_sum"])
    if not data["next"]:
        break
    page += 1

Credits and pricing

Credits per request for every endpoint.

Production checklist

Guard your spend before going live.

Last modified on October 28, 2026

Get started

Contact data

People and companies

Account and billing

Production

Help

Coming soon

Check credit usage from the API

Total spent this month

List balance changes

Credits and pricing

Production checklist

​Total spent this month

​List balance changes

​Related

Credits and pricing

Production checklist

Total spent this month

List balance changes

Related