---
title: "The credit spend ledger"
method: POST
path: "/business/credits/usage"
tags: ["Account"]
---

# The credit spend ledger

`POST /business/credits/usage`

## Request

- Base URL: `https://api.tryfuse.ai/api/v1`
- URL: `https://api.tryfuse.ai/api/v1/business/credits/usage`
- Auth: HTTP basic

The credit spend ledger for a `since` / `to` window (`to` omitted = up to now) and an optional `memberIds` teammate filter — the same contract as the internal spend endpoint, all echoed back (`to` as null and `memberIds` as [] when omitted): `usage` is the current billing period's headline (used, available, total, period bounds, and the AppSumo one-time holdback when one applies), and `spendByDateByProduct` is the zero-filled spend series over the window, each point carrying its deductions split by product. Points are time buckets sized by the window's length — daily while it spans at most 13 days, otherwise weekly (ISO weeks), monthly or quarterly — so a one-month window comes back by week and a one-year window by month. Each point carries `isoDate` (the bucket's start day, YYYY-MM-DD UTC) and `date` (a display label for that start: `Sep 1` for daily and weekly buckets, `Sep` for monthly, `Sep 2026` for quarterly). Sum a point's products for the bucket's total; sum a product across points for its window total. Omit `memberIds` (or pass `[]`) for the whole ledger; pass teammate ids to restrict the series to those people's deductions, including the owner id for the owner's own untagged charges. Each of the two panels is null when its lookup fails. Available to any valid key (no scope needed). Rate limit: 120 requests per minute, 10000 per day.

Errors:
- `403` `TEAM_MEMBER_NOT_IN_SCOPE` — A `memberIds` entry is not an active member of the caller's team.
- `422` `VALIDATION_FAILED` — `since` is missing or not an ISO 8601 date, `to` is not an ISO 8601 date or precedes `since`, or a `memberIds` entry is not a 24-character hex id.
- `429` `RATE_LIMITED` — Per-user quota for this endpoint family exceeded (120 per minute, 10000 per day); retry after the Retry-After / RateLimit-Reset seconds.

## Request body

- object
  - `since` string, date-time, required: Start of the spend window (inclusive) as an ISO 8601 date-time instant, e.g. 2026-08-01T00:00:00.000Z. Do not send a date-only YYYY-MM-DD. Must not be in the future. `spendByDateByProduct` is bucketed by the window's length — daily while it spans at most 13 days, then weekly (ISO weeks), monthly or quarterly — while `usage` always reflects the current billing period regardless of the window.
  - `to` string, date-time: End of the spend window (inclusive) as an ISO 8601 date-time instant; must not precede `since`. Omit to run the window up to now. Do not send a date-only YYYY-MM-DD.
  - `timezone` string: IANA timezone name (e.g. `Europe/Kyiv`, `America/New_York`) whose calendar days `spendByDateByProduct` is bucketed by: each point's `isoDate` / `date` is a local day, week, month or quarter in this zone. Send the zone `since` / `to` were computed in — for a local day range, `since` is local midnight and `to` local end-of-day. Offsets such as `+03:00` are rejected. Default: `UTC`.
  - `memberIds` string[]: Restrict `spendByDateByProduct` to these teammates' deductions. Omit or pass `[]` for the whole ledger (every teammate sees the same default). Each id must be an active member of the caller's team; including the owner adds the owner's own untagged charges. Any id outside the team answers 403 `TEAM_MEMBER_NOT_IN_SCOPE`. `usage` always reflects the current billing period regardless of this filter.

## Response `200`

Success

- object
  - `since` string, date-time, required
  - `to` string, date-time, nullable, required
  - `memberIds` string[], required
  - `usage` object, nullable, required
    - `used` integer, required
    - `available` integer, required
    - `total` integer, required
    - `periodStartDate` string, date-time, required
    - `periodEndDate` string, date-time, required
    - `oneTimeCreditsHoldback` object, nullable, required
      - `heldCredits` integer, required
      - `releaseAt` string, date-time, required
  - `spendByDateByProduct` object[], nullable, required
    - `date` string, required
    - `isoDate` string, date, required
    - `products` object[], required
      - `product` 'Phone Enrichment' | 'Email Enrichment' | 'Email Validation' | 'Email Warmup' | 'Website Traffic' | 'AI Engagement' | 'Call Recording & Transcripts' | 'Fuse Agent Message' | 'Saving to List' | 'Buying Domains' | 'Buying Mailboxes' | 'Charging Mailbox Subscription' | 'Charging Domain Subscription' | 'Charging LinkedIn Account Subscription' | 'Prospect Search' | 'Company Search' | 'Global Phone Number Search' | 'Phone Number Rent' | 'Signal Monitor Webhook' | 'People Watcher Setup' | 'Companies Watcher Setup' | 'Companies Watcher Recurring' | 'People Watcher Recurring' | 'Smart Column Enrichment' | 'Job Changes Watcher Delivery' | 'Web Monitor Result' | 'Deep Research Action' | 'Automation Run', required
      - `value` integer, required

## Other responses

- `400`: Error
- `401`: Error
- `402`: Error
- `403`: Error
- `404`: Error
- `409`: Error
- `422`: Error
- `429`: Error
- `500`: Error

---

[API](https://skmtc.dev/fuseai/apis/fuse-business-api.md) · [All operations](https://skmtc.dev/fuseai/apis/fuse-business-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fuseai/apis/fuse-business-api/revisions/50d95e0536f4?raw)