Tool credits are the one pool of credits your agent spends when it runs paid work through granvl: research reports, competitor ads, keyword data, web research, and image and video generation. Each call costs what the provider charged plus a small margin, and you're charged only when the call succeeds.

Before you begin

Anyone in the workspace with the Owner, Admin, or Member role can spend Tool credits through their agent.
Only an Owner or Admin can buy credit packs or change which regions models may be served from.
Your agent must be connected to granvl. See Connect Claude, ChatGPT, Grok Bot, Cursor, or another agent.

What Tool credits pay for

Work	Tools your agent calls	How the cost is handled
Research reports for an offer, a niche, or a breakout	`start_offer_research`, `start_niche_research`, `start_breakout_research`	Estimate first, then charged when the report completes
Going deeper on a report	`deepen_offer_research`	Quote sections cost about 2 credits a query. Re-pulling keywords or ads is metered separately; ads with landing-page teardowns can run 30 to 40 credits.
Competitor ads from the ad library	`research_competitor_ads`	Estimate first
A landing page teardown	`research_landing_page`	A few credits, estimate first
Keyword volume, CPC, and bids	`research_keywords`, `plan_search_campaign`	A few credits, runs without asking
Cited web research	`research_web`	A small cost, reported in the result
Image generation	`generate_image`	Confirm first when it costs more than 20 credits
Video generation	`generate_video`	Confirm first when it costs more than 20 credits. Charged when the clip is ready.
Hosted analysis	`compare_ad_sets` and AI funnel analysis when it's turned on	Drawn from the same pool

These are free and never spend credits: list_competitor_ads (ads already saved in Research), build_keyword_plan, classify_keywords, compose_creative_brief, list_capabilities, and get_credits. Ask your agent to check saved ads with list_competitor_ads before paying to pull a competitor again.

For the research workflows, see Research an offer with research reports and Study competitor ads and landing pages.

Models and regions

Your agent picks a model by name. list_capabilities returns the models your workspace may use, where each is served from, its rough price in credits, and your balance.

Kind	Models
Images	GPT Image 2, Nano Banana 2.1, FLUX.2 Pro (served from the EU), Seedream 4.5 (served from Singapore)
Video	Veo 3.1, Seedance 2.5 (served from Singapore)
Web research	Sonar Pro, Sonar

The list can change, so ask your agent to call list_capabilities for the current one. A video clip costs far more than an image. Larger image sizes (2K, 4K) and longer or higher-resolution clips cost more.

To limit where requests may be served, open Settings > AI / MCP, find Generation regions, and click Edit. Tick the regions you allow (United States, European Union, Singapore), then click Save regions. All three are on by default. Models served from a region you turn off are hidden from your agent and refused.

See the cost before you spend

granvl is set up so your agent quotes a cost before anything expensive runs.

Research tools accept estimate_only: true. That call returns estimated_credits (and estimated_minutes for reports) and runs nothing. The tool instructions tell your agent to make this call first, tell you the cost, and run the real call only after you say yes.
Image and video generation above 20 credits returns needs_confirmation with estimated_credits instead of running. This check happens on granvl's side. Your agent asks you, then calls again with confirm: true.

A prompt you can use:

Before you run anything that costs Tool credits, call it with estimate_only first and tell me the cost. Wait for my yes.

One pool per workspace

Everyone in the workspace draws on the same pool, and so does every agent connected to it.
The pool is your monthly allowance plus any packs you bought. New workspaces get 500 monthly credits by default; your exact allowance shows under Monthly credits in Settings > AI / MCP.
The monthly allowance resets on the first day of each month (UTC). Unused monthly credits don't carry over.
Purchased credits never expire. They're used only after the month's allowance runs out, and whatever is left carries into the next month.
Credits that support grants you count for the month they're granted, unless support gives them a different end date.

The spend guard

Before any generation or research call, granvl checks four limits. Each fails on its own, so one problem can't leave spending open.

Role. The caller must be an Owner, Admin, or Member of the workspace.
Burst limits. A short-term limit on how fast the workspace, and each person, can run calls.
Daily call limit. A cap on how many generation and research calls the workspace makes in a day.
Daily credit ceiling. By default, 2,000 credits of generation and research in any 24 hours.

Then granvl checks the balance covers the call. If any check fails, nothing runs and nothing is charged. Your agent shows the reason:

Message starts with	What it means	What to do
"This workspace is generating and researching faster than allowed"	The workspace hit the burst limit	Wait a few minutes and try again
"You are generating and researching faster than allowed"	You hit your personal burst limit	Wait a few minutes and try again
"This workspace has used its daily allowance of generation and research calls"	Too many calls today	It resets within 24 hours
"This workspace has reached its daily capability spending limit"	The 24-hour credit ceiling is reached. The message shows the limit and how much was used.	Wait while earlier spend ages out, or an Owner can ask [email protected] to raise it
"Not enough credits"	The balance can't cover the call. The message shows what it needs and what's left.	Buy a credit pack, then retry
"... is served from ..., which this workspace does not allow"	The model's region is turned off	Pick another model, or change Generation regions

Check your balance

Dashboard header: the credits counter shows the Tool credits you have left. Click it to see "N of M monthly credits left" and the reset date.
Settings > AI / MCP: Monthly credits shows what's left and used, Usage this month breaks spending down by feature, and Credit history lists every movement.
Your agent: get_credits returns toolCredits (remaining, used, total, and when the monthly part resets), plus your verification credits and validation allowances. list_capabilities also returns the balance.

How many Tool credits do we have left this month?

Buy a credit pack

Click the Tool credits counter in the dashboard header.
Choose a pack: 2,000 credits ($20), 5,000 credits ($50), or 10,000 credits ($100).
Click Buy 5,000 credits (the button shows the pack you chose).
Pay on Stripe's checkout page.
Stripe returns you to the page you were on. The credits land as soon as Stripe confirms the payment.

The Tool credits window with the 2,000, 5,000 and 10,000 credit packs

If you aren't an Owner or Admin, the window says "Only workspace owners and admins can buy credits."

Note: Buy credits on Settings > Billing sells verification credits for SMS codes and validation, not Tool credits.

How charges show up

Generation results include credits_charged and your remaining balance.
Failed or cancelled calls are never charged. A video job still pending after 2 hours is written off and never charged.
Settings > AI / MCP > Usage this month groups spending by feature, such as Image generation, Video generation, and Research and data.
Credit history lists each spend by feature, Credit pack purchased, Pack refunded, and Credits granted, with who and when.

Only the prompt or query you wrote and the reference files you chose are sent to the provider. Lead details and your workspace context never are. See Understand how granvl handles lead data.

Use Tool credits for research and generation