sessions changedmanaged-agents/sessions
Recorded here
Lines+128added
Lines−21removed
From line
800
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits18to this page, all time
The whole hunk
from line 800, old and new numbered
/
from line 800
800800
801801### Set a session budget
802802
803To cap what a session can spend, pass the optional `budget` object when you create it. A budget is a hard ceiling on the session's list cost: the platform prices everything the session consumes at public list rates, and the session stops issuing new model requests once that running total reaches `max_list_cost`. Set `type` to `limit` and give `max_list_cost` an `amount` and a `currency`. `amount` is a whole number of US cents written as a string, such as `"2500"` for $25.00; the API takes a string rather than a number so no floating-point rounding is ever applied. `USD` is the only currency currently supported. When the session reaches the cap, it pauses and goes idle with the stop reason `budget_reached`. The cap is enforced between model requests, so the request that crosses it finishes first and the session's final list cost can land [a fraction past the cap](https://platform.claude.com/docs/en/managed-agents/budgets#when-a-session-reaches-its-budget). A budget can only be attached at creation: you can [change or remove](https://platform.claude.com/docs/en/managed-agents/session-operations#updating-the-session-budget) it later, but you can't add one to a session created without it.
803To cap what a session can spend, pass the optional `budget` object when you create it. A budget is a hard ceiling on the session's list cost: the platform prices everything the session consumes at public list rates, and the session stops issuing new model requests once that running total reaches `max_list_cost`. Set `type` to `limit` and give `max_list_cost` an `amount` and a `currency`. `amount` is a whole number of US cents written as a string, such as `"125"` for $1.25. The API takes a string rather than a number so no floating-point rounding is ever applied. `USD` is the only currency currently supported. When the session reaches the cap, it pauses and goes idle with the stop reason `budget_reached`. The cap is enforced between model requests, so the request that crosses it finishes first and the session's final list cost can land [a fraction past the cap](https://platform.claude.com/docs/en/managed-agents/budgets#when-a-session-reaches-its-budget). A budget can only be attached at creation: you can [change or remove](https://platform.claude.com/docs/en/managed-agents/session-operations#updating-the-session-budget) it later, but you can't add one to a session created without it.
804804
805The following example creates a session with a $25.00 budget; the response echoes the `budget` on the session resource:
805The following example creates a session with a $1.25 budget:
806806
807```bash cURL
808curl -fsSL https://api.anthropic.com/v1/sessions \
809 -H "x-api-key: $ANTHROPIC_API_KEY" \
810 -H "anthropic-version: 2023-06-01" \
811 -H "anthropic-beta: managed-agents-2026-04-01" \
812 -H "content-type: application/json" \
813 -d @- <<EOF
814{
815 "agent": "$AGENT_ID",
816 "environment_id": "$ENVIRONMENT_ID",
817 "budget": {
818 "type": "limit",
819 "max_list_cost": {"amount": "2500", "currency": "USD"}
807<CodeGroup>
808 ```bash cURL
809 curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
810 -H "x-api-key: $ANTHROPIC_API_KEY" \
811 -H "anthropic-version: 2023-06-01" \
812 -H "anthropic-beta: managed-agents-2026-04-01" \
813 -H "content-type: application/json" \
814 -d @- <<EOF
815 {
816 "agent": "$AGENT_ID",
817 "environment_id": "$ENVIRONMENT_ID",
818 "budget": {
819 "type": "limit",
820 "max_list_cost": {"amount": "125", "currency": "USD"}
821 }
820822 }
821}
822EOF
823```
823 EOF
824 ```
825
826 ```bash CLI
827 # Keep the amount quoted so it is sent as a string, not a number.
828 ant beta:sessions create \
829 --agent "$AGENT_ID" \
830 --environment-id "$ENVIRONMENT_ID" \
831 --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}'
832 ```
833
834 ```python Python
835 session = client.beta.sessions.create(
836 agent=agent.id,
837 environment_id=environment.id,
838 budget={
839 "type": "limit",
840 "max_list_cost": {"amount": "125", "currency": "USD"},
841 },
842 )
843 print(session.id, session.budget.max_list_cost.amount) # sesn_01... 125
844 ```
845
846 ```typescript TypeScript
847 const session = await client.beta.sessions.create({
848 agent: agent.id,
849 environment_id: environment.id,
850 budget: {
851 type: "limit",
852 max_list_cost: { amount: "125", currency: "USD" }
853 }
854 });
855 console.log(session.id, session.budget?.max_list_cost.amount); // sesn_01... 125
856 ```
857
858 ```csharp C#
859 var session = await client.Beta.Sessions.Create(new()
860 {
861 Agent = agent.ID,
862 EnvironmentID = environment.ID,
863 Budget = new()
864 {
865 Type = BetaManagedAgentsBudgetLimitType.Limit,
866 MaxListCost = new() { Amount = "125", Currency = BetaCurrency.Usd },
867 },
868 });
869 Console.WriteLine($"{session.ID} {session.Budget?.MaxListCost.Amount}"); // sesn_01... 125
870 ```
871
872 ```go Go
873 session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
874 Agent: anthropic.BetaSessionNewParamsAgentUnion{
875 OfString: anthropic.String(agent.ID),
876 },
877 EnvironmentID: environment.ID,
878 Budget: anthropic.BetaManagedAgentsBudgetLimitParam{
879 Type: anthropic.BetaManagedAgentsBudgetLimitTypeLimit,
880 MaxListCost: anthropic.BetaMonetaryAmountParam{
881 Amount: "125",
882 Currency: anthropic.BetaCurrencyUsd,
883 },
884 },
885 })
886 if err != nil {
887 panic(err)
888 }
889 fmt.Println(session.ID, session.Budget.MaxListCost.Amount) // sesn_01... 125
890 ```
891
892 ```java Java
893 var session = client.beta().sessions().create(SessionCreateParams.builder()
894 .agent(agent.id())
895 .environmentId(environment.id())
896 .budget(BetaManagedAgentsBudgetLimit.builder()
897 .type(BetaManagedAgentsBudgetLimit.Type.LIMIT)
898 .maxListCost(BetaMonetaryAmount.builder()
899 .amount("125")
900 .currency(BetaCurrency.USD)
901 .build())
902 .build())
903 .build());
904 IO.println(session.id() + " " + session.budget().orElseThrow().maxListCost().amount()); // sesn_01... 125
905 ```
906
907 ```php PHP
908 $session = $client->beta->sessions->create(
909 agent: $agent->id,
910 environmentID: $environment->id,
911 budget: [
912 'type' => 'limit',
913 'max_list_cost' => ['amount' => '125', 'currency' => 'USD'],
914 ],
915 );
916 echo "{$session->id} {$session->budget->maxListCost->amount}\n"; // sesn_01... 125
917 ```
918
919 ```ruby Ruby
920 session = client.beta.sessions.create(
921 agent: agent.id,
922 environment_id: environment.id,
923 budget: {
924 type: "limit",
925 max_list_cost: {amount: "125", currency: "USD"}
926 }
927 )
928 puts "#{session.id} #{session.budget.max_list_cost.amount}" # sesn_01... 125
929 ```
930</CodeGroup>
824931
825932See [Session budgets](https://platform.claude.com/docs/en/managed-agents/budgets) for how enforcement works, what counts toward list cost, and how budgets behave in multiagent sessions.
826933
No line in this hunk matches that.