How to Set Task Budgets in Claude Fable 5

A practical, code-first walkthrough of Anthropic’s task-budgets beta — what it actually caps, how to size one, and where it quietly fails if you set it wrong.

By Oyekale Olawale

Three weeks ago I let a Claude Fable 5 agent loose on a genuinely messy codebase audit and walked away for twenty minutes. When I came back, it was still going, still calling tools, still thinking out loud in ever-longer bursts. The bill for that one unsupervised run was more than I’d normally spend testing an entire tool for a review. That’s the moment I actually went and read the task-budgets documentation properly instead of skimming it, and it’s the reason this guide exists.

Quick Answer

To set a task budget, add a task_budget object inside output_config on your Messages API call ({"type": "tokens", "total": 64000}) and send the beta header task-budgets-2026-03-13. The minimum accepted total is 20,000 tokens. It’s a soft, advisory cap on the full agentic loop — thinking, tool calls, tool results, and output combined — not a hard stop. Pair it with max_tokens if you need an actual ceiling. It works on Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, and Claude Opus 4.7, but it is not available inside Claude Code or Cowork.

What a Task Budget Actually Is

A task budget is Anthropic’s way of giving Claude Fable 5 an advisory token allowance for an entire agentic loop, rather than for a single request. Once you set one, the model sees a running countdown injected into its context as it thinks, calls tools, and processes tool results. Claude uses that countdown to pace itself — reasoning less aggressively as the budget shrinks and trying to wrap up with a summary or partial result instead of getting cut off mid-action.

This is different from a per-request limit. A single agentic task on Fable 5 might span a dozen API calls as it lists files, greps for patterns, edits code, and re-checks its work. max_tokens caps what comes back on any one of those calls. A task budget caps the sum of everything Claude sees and generates across the whole chain, until the loop ends with stop_reason: "end_turn".

If you’ve read our breakdown of how Claude Fable 5 performs in real testing, you already know the model is built for long-horizon, multi-step work. Task budgets exist specifically because that kind of work is where token spend gets unpredictable fastest.

Why You’d Bother Setting One

Task budgets make the most sense for agentic workflows where Claude is making its own decisions across several tool calls before handing control back to a human. Three situations in particular:

• You want the model to self-regulate spend on tasks that could otherwise run long — code migrations, research loops, multi-file refactors.
• You have a per-task cost or latency ceiling you need to plan around, and unpredictable agent loops make that planning impossible.
• You’d rather Claude finish gracefully — reporting progress, summarizing what it found — than get abruptly truncated mid-tool-call.

Fable 5 bills at $10 per million input tokens and $50 per million output tokens, which is exactly double Claude Opus 4.8’s rate. Output-heavy agentic loops are where that multiplier hurts most, since thinking tokens count as output. A task budget won’t lower the per-token price, but it gives the model a reason to stop reasoning once it’s found the answer instead of continuing to deliberate.

Step-by-Step: Setting a Task Budget

Step 1: Confirm your model supports it

Task budgets are in beta on Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, and Claude Opus 4.7. Sonnet and Haiku-class models don’t support the parameter at all — sending it there returns an error, not a silent no-op.

Step 2: Set the beta header

Every request that includes task_budget needs the beta flag task-budgets-2026-03-13 passed in the betas array (or as an HTTP header if you’re calling the raw REST endpoint). Forget this and the parameter is ignored.

Step 3: Add task_budget to output_config

Here’s what it looks like in the Python SDK:

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-fable-5",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 64000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
) as stream:
    response = stream.get_final_message()

print(response.usage)

The task_budget object takes three fields: type (always "tokens"), total (the ceiling for the whole loop, minimum 20,000), and an optional remaining field you only need when you’re carrying a budget across a compaction event — more on that below.

Step 4: Set max_tokens as a real ceiling

Because the task budget is advisory, pair it with a sensible max_tokens value on each request. At xhigh or max effort, Anthropic recommends at least 64k so Claude has room to think and act without hitting a hard wall mid-response.

Step 5: Let the model self-regulate — don’t try to mirror the countdown yourself

This is the step people skip, and it’s the one that causes the most confusion. Set a generous total once, and let Claude track its own spend against the server-side countdown. Don’t try to recompute remaining client-side on every turn unless you’re specifically carrying a budget across a compaction step.

How the Countdown Actually Works

Here’s the part that trips people up: the countdown is visible only to the model. Nothing in the API response tells you the remaining budget — there’s no task_budget field in usage, and no SDK accessor for it. If you want to track spend on your end, you sum token usage across every request in the loop yourself.

The other detail worth internalizing: the budget counts what Claude processes each turn, not what your client resends. In a typical agentic loop your client resends the full conversation history on every follow-up request — but the countdown only decrements by the new content Claude actually sees that turn (a new tool result, new thinking, a new tool call). The resent history from earlier turns isn’t charged again.

Worked example based on a 100,000-token budget with a single bash tool, adapted from Anthropic’s documentation. The client sent roughly 20,820 tokens cumulatively across three requests, but the budget only tracked the 19,000 tokens Claude actually generated or processed.

Choosing the Right Budget Size

Don’t guess. Run a representative sample of your actual tasks without a task budget set, and sum the total tokens Claude spends per task across the whole loop — output tokens, thinking tokens, and tool-result tokens combined. Then look at the p99 of that distribution as your starting budget, and adjust from there.

The floor is fixed: task_budget.total below 20,000 tokens returns a 400 error, full stop. And a budget that’s technically valid but genuinely too small for the job creates its own problem — the model may decline to attempt the task, scope it down aggressively, or stop early with a partial result rather than start work it can’t finish. If you’re seeing unexpected refusals or premature stops right after adding a budget, raise the number before you touch anything else.

Task Budget vs. Effort vs. max_tokens

These three parameters get confused constantly, so here’s how they actually divide the work. If you’re still deciding how deep to set reasoning on a given call, our guide on structuring long-context prompts for Claude Fable 5 covers the effort side of this in more depth.

Because task budgets include thinking tokens in the running total, adaptive thinking on Fable 5 naturally scales down as the budget depletes — you don’t need to separately throttle effort as the loop winds down.

Carrying a Budget Across Compaction

If your agentic loop compacts or summarizes earlier turns between requests, the server loses track of how much budget was already spent — compaction wipes that history. Pass the remaining field explicitly so the countdown picks up where it left off, instead of resetting to the full total:

output_config = {
    "effort": "high",
    "task_budget": {
        "type": "tokens",
        "total": 128000,
        "remaining": 128000 - tokens_spent_so_far,
    },
}

For loops that resend the full uncompacted conversation on every turn, skip remaining entirely and let the server-side countdown handle it. Mutating remaining unnecessarily just introduces a value that changes every request.

The Prompt Caching Trap

This is the mistake I actually made on that twenty-minute audit run. The budget-countdown marker gets injected server-side into every turn, so it never matches across requests by design. If you decrement task_budget.remaining yourself on each follow-up call, that changing value invalidates any cache prefix that contains it — you lose your prompt-cache discount on every single turn.

The fix is the same advice as before: set the budget once on the initial request and don’t touch it again unless you’re specifically recovering from a compaction event. Prompt caching drops input costs from $10 to roughly $1 per million tokens on repeated content, and that’s too large a discount to throw away over a budget field you didn’t need to update anyway.

Where This Sits in the Fable 5 Pricing Picture

Claude Fable 5 and Claude Mythos 5 share the same rate card: $10 per million input tokens, $50 per million output tokens, a 1M-token context window by default, and up to 128k output tokens per request. That output rate is what makes agentic loops expensive — every reasoning pass and tool call the model runs is billed as output. A task budget is one of the few levers that directly targets that line item, alongside batch processing (roughly half price for offline work) and prompt caching for repeated context.

Worth knowing if you’re evaluating whether Fable 5 is worth the premium at all: our comparison of Claude Fable 5 against ChatGPT 5.5 digs into where the extra cost pays off and where it doesn’t, and our look at hallucination rates between Claude and ChatGPT is relevant if accuracy on long unsupervised runs is your main concern rather than cost.

Common Mistakes When Setting Task Budgets

Most of the friction people hit with this beta feature traces back to one of five habits carried over from working with max_tokens, which behaves very differently.

• Treating it as a hard stop. It isn’t. If you need a guaranteed ceiling, that’s what max_tokens is for — task budgets are a pacing signal, not a circuit breaker.
• Sizing the budget off a guess instead of measured usage. Guessed budgets tend to land either too tight, which triggers early stops or refusal-like behavior, or too loose to matter at all.
• Recomputing remaining on every follow-up call. This double-penalizes the model — it under-reports the true budget and breaks prompt-cache prefixes at the same time.
• Forgetting the beta header. Without task-budgets-2026-03-13 in the betas array, the task_budget field is silently ignored rather than erroring loudly, which makes the mistake easy to miss during testing.
• Trying to use it on an unsupported model. Sonnet 4.6 and Haiku 4.5 don’t accept the parameter at all — check the support table above before you spend time debugging what looks like a bug but is actually a model mismatch.

None of these are exotic edge cases — they’re the first five things almost anyone runs into within a day of turning the beta on, myself included.

One Big Limitation: Not in Claude Code or Cowork

Task budgets are a Messages API feature only. They are not supported on Claude Code or Cowork surfaces, so if you’re running Fable 5 inside either of those tools rather than calling the API directly, this parameter simply isn’t available to you yet. If you’ve been noticing slower or seemingly stalled sessions inside those tools, that’s a separate issue — our fix guide for Claude taking longer than usual covers the more common causes.

If you’re building your own agent orchestration on top of the Messages API — which is where task budgets actually live — it’s also worth reading how long-context prompts behave differently on Fable 5, since budget sizing and context length interact more than the docs make obvious at first glance.

FAQ

Is a task budget a hard limit on spend?

No. It’s advisory. Claude can exceed it if stopping mid-action would be more disruptive than finishing. For an actual hard ceiling, combine task_budget with max_tokens.

What’s the minimum task budget I can set?

20,000 tokens. Anything lower returns a 400 error from the API.

Which models support task budgets?

Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, and Claude Opus 4.7, all in beta behind the task-budgets-2026-03-13 header. Opus 4.6, Sonnet 4.6, and Haiku 4.5 do not support it.

Can I see the remaining budget in the API response?

No. The countdown is only visible to the model internally. You have to sum token usage across your own requests if you want to track spend client-side.

Why did Claude refuse or stop early right after I set a budget?

The budget is probably too small for the task. Claude may decline, scope down, or stop with a partial result when it sees a budget it judges insufficient — for example, 20,000 tokens for a multi-hour coding job. Raise the total before adjusting anything else.

Does a task budget work inside Claude Code?

Not currently. Task budgets are a Messages API parameter and aren’t supported on Claude Code or Cowork surfaces.

Does setting a task budget affect prompt caching?

Only if you change remaining on every request. Set the total once and leave it alone to preserve your cache prefix and the associated discount.

Bottom Line

Task budgets won’t stop a Fable 5 agent from occasionally running over, and they won’t lower the $10/$50 rate card. What they will do is give the model a reason to pace itself and wrap up gracefully instead of grinding through an open-ended loop at your expense. Measure your real usage first, set the total at your p99, pair it with a sane max_tokens, and — this is the part I learned the expensive way — leave remaining alone unless you’re actually recovering from compaction. That’s the whole system. It’s simple once you’ve seen it fail once.