BrightBean docs

Credits budgeting

Per-call cost reference

Call Credits
score_packaging — title only 1
score_packaging — thumbnail only 2
score_packaging — title + thumbnail 3
score_video_hook 10
research_content_gaps 5
list_niches 1
benchmark_channel 5
benchmark_video 3
GET /v1/me/, GET /v1/usage/ free

score_packaging auto-detects the mode from your inputs — passing both title and thumbnail charges 3 credits and captures interaction effects the single-input modes miss.

Credits debit only on success (2xx). Anything else is free.

Estimating a workload

For a typical channel-audit agent that scores the packaging of 50 published videos, then deep-dives the hooks of the 3 weakest performers:

50 × score_packaging   = 150 credits  (title + thumbnail)
 3 × score_video_hook  =  30 credits
                          ---
                          180 credits / run

score_video_hook only scores published YouTube videos — see the score_video_hook reference for accepted URL formats.

A free-tier account (350 credits) covers a single run. A Starter account (10,000/day) can do 55 runs/day.

Watching the balance

In-app: app.brightbean.xyz/settings/usage. Programmatic:

usage = client.usage()
print(usage.credits_remaining, usage.plan.daily_limit)

Or via the CLI:

brightbean usage --pretty

Capping a run

Two ways to make a long-running job stop cleanly:

1. Pre-check the balance:

needed = 50 * 3  # 50 packaging calls
have = (client.usage()).credits_remaining
if have < needed:
    raise SystemExit(f"need {needed}, have {have}")

2. Stop on InsufficientCreditsError:

from brightbean import InsufficientCreditsError

try:
    for title in titles:
        client.score(title=title)
except InsufficientCreditsError:
    print("out of credits — pausing")

The error fires the moment the server determines the call would overdraw — never mid-call.

Tips