> ## Documentation Index
> Fetch the complete documentation index at: https://www.forager.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Forager is a REST API for B2B people, company and job post data: contact lookups (phone numbers, personal emails, work emails), person, company and job post search, and bulk data feeds.
> Server: https://api-v2.forager.ai. Send the API key in the X-API-KEY header. Most paths include {account_id}. Read FORAGER_API_KEY and FORAGER_ACCOUNT_ID from the environment; never put the key in client-side code, logs or prompts.
> To add Forager to a project, follow https://www.forager.ai/docs/guides/agent-quickstart.md. To pick an endpoint, read https://www.forager.ai/docs/guides/choose-an-endpoint.md. For end-to-end builds, see https://www.forager.ai/docs/recipes/overview.md.
> Most requests spend credits. Do not guess costs; use https://www.forager.ai/docs/api-overview/credit-pricing.md and ask the user before spending credits.
> Use only endpoints and fields defined in https://www.forager.ai/docs/openapi.yaml. Forager has no MCP server for the API yet; the /mcp endpoint on this site searches the documentation only.

# Check credit usage from the API

> Track Forager credit spend from code: list credit balance changes and get total credits spent for a date range with the balance change log endpoints.

![API credit usage: the balance change log and credit totals endpoints](https://mintcdn.com/forager/EGsWCxLOYv1Cb__c/images/illustrations/api-credit-usage-balance-log.svg?fit=max\&auto=format\&n=EGsWCxLOYv1Cb__c\&q=85\&s=4b0cb2c48f259a35cd66a2b39288c0b7)

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](https://app.forager.ai/subscription).

| You want | Endpoint | Query parameters |
| - | - | - |
| Every balance change, with type, amount and description | [Credit balance change log](https://www.forager.ai/docs/openapi/users/subscriptions_balance_change_logs_list.md) | `date_created_start`, `date_created_end`, `page` |
| Total credits spent in a period | [Credit consumption totals](https://www.forager.ai/docs/openapi/users/subscriptions_balance_change_logs_totals_retrieve.md) | `date_created_start`, `date_created_end` |

## Total spent this month

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"])
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```

## Related

> [card] [Credits and pricing](https://www.forager.ai/docs/api-overview/credit-pricing.md)
>
> Credits per request for every endpoint.

> [card] [Production checklist](https://www.forager.ai/docs/guides/production-checklist.md)
>
> Guard your spend before going live.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.