> For the complete documentation index, see [llms.txt](https://docs.otari.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otari.ai/otari/for-integrators/api-reference/scoped-budgets.md). # Scoped budgets ## List Scoped Budgets > List the scoped budgets in the caller's organization, optionally filtered to one scope. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"ScopedBudgetResponse":{"description":"One scoped ceiling and its live counters.\n\nUnlike ``/api/v1/budgets``, the counters are the row's own: a scoped ceiling is\nenforced against ``current_spend + reserved_spend``, so there is no rollup\nover users to compute.\n\nEvery limit, along with ``budget_duration_sec`` and ``reset_alignment``, is\nread off the budget rather than stored here, and carried on the wire so a\ncaller can render a ceiling without fetching every budget to resolve one id.","properties":{"budget_duration_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Duration Sec"},"budget_id":{"title":"Budget Id","type":"string"},"created_at":{"title":"Created At","type":"string"},"current_requests":{"title":"Current Requests","type":"integer"},"current_spend":{"title":"Current Spend","type":"number"},"current_tokens":{"title":"Current Tokens","type":"integer"},"id":{"title":"Id","type":"string"},"max_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Budget"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period End"},"period_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Start"},"provider_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Key Id"},"request_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Limit"},"reserved_requests":{"title":"Reserved Requests","type":"integer"},"reserved_spend":{"title":"Reserved Spend","type":"number"},"reserved_tokens":{"title":"Reserved Tokens","type":"integer"},"reset_alignment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reset Alignment"},"scope_id":{"title":"Scope Id","type":"string"},"scope_type":{"title":"Scope Type","type":"string"},"token_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Token Limit"},"updated_at":{"title":"Updated At","type":"string"}},"required":["id","scope_type","scope_id","provider_key_id","budget_id","name","max_budget","current_spend","reserved_spend","token_limit","current_tokens","reserved_tokens","request_limit","current_requests","reserved_requests","budget_duration_sec","reset_alignment","period_start","period_end","created_at","updated_at"],"title":"ScopedBudgetResponse","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/scoped-budgets":{"get":{"description":"List the scoped budgets in the caller's organization, optionally filtered to one scope.","operationId":"scoped-budgets-list_scoped_budgets","parameters":[{"in":"query","name":"scope_type","required":false,"schema":{"anyOf":[{"enum":["organization","workspace","workspace_member","org_member","api_token"],"type":"string"},{"type":"null"}],"title":"Scope Type"}},{"in":"query","name":"scope_id","required":false,"schema":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"title":"Scope Id"}},{"in":"query","name":"skip","required":false,"schema":{"default":0,"minimum":0,"title":"Skip","type":"integer"}},{"in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":1000,"minimum":1,"title":"Limit","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ScopedBudgetResponse"},"title":"Response Scoped-Budgets-List Scoped Budgets","type":"array"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List Scoped Budgets","tags":["scoped-budgets"]}}}} ``` ## Create Scoped Budget > Create a scoped budget.\ > \ > Answers 404 when the scope names nothing, rather than creating a ceiling\ > that can never bind. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"CreateScopedBudgetRequest":{"description":"Request model for creating a scoped budget.","properties":{"budget_id":{"description":"The budget this ceiling enforces; its limit and period are read through it","maxLength":255,"minLength":1,"title":"Budget Id","type":"string"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"description":"Admin-facing label for this ceiling","title":"Name"},"provider_key_id":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^\\S+$","type":"string"},{"type":"null"}],"description":"Narrow the cap to one provider instance; omit or null to cap spend across every provider. A blank value would store a ceiling that never binds, so it is refused; this does not check that the value names a configured provider instance","title":"Provider Key Id"},"scope_id":{"description":"Id of the capped identity: an organization, workspace, membership row, or API key","maxLength":255,"minLength":1,"title":"Scope Id","type":"string"},"scope_type":{"description":"Which kind of identity this ceiling caps","enum":["organization","workspace","workspace_member","org_member","api_token"],"title":"Scope Type","type":"string"}},"required":["scope_type","scope_id","budget_id"],"title":"CreateScopedBudgetRequest","type":"object"},"ScopedBudgetResponse":{"description":"One scoped ceiling and its live counters.\n\nUnlike ``/api/v1/budgets``, the counters are the row's own: a scoped ceiling is\nenforced against ``current_spend + reserved_spend``, so there is no rollup\nover users to compute.\n\nEvery limit, along with ``budget_duration_sec`` and ``reset_alignment``, is\nread off the budget rather than stored here, and carried on the wire so a\ncaller can render a ceiling without fetching every budget to resolve one id.","properties":{"budget_duration_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Duration Sec"},"budget_id":{"title":"Budget Id","type":"string"},"created_at":{"title":"Created At","type":"string"},"current_requests":{"title":"Current Requests","type":"integer"},"current_spend":{"title":"Current Spend","type":"number"},"current_tokens":{"title":"Current Tokens","type":"integer"},"id":{"title":"Id","type":"string"},"max_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Budget"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period End"},"period_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Start"},"provider_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Key Id"},"request_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Limit"},"reserved_requests":{"title":"Reserved Requests","type":"integer"},"reserved_spend":{"title":"Reserved Spend","type":"number"},"reserved_tokens":{"title":"Reserved Tokens","type":"integer"},"reset_alignment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reset Alignment"},"scope_id":{"title":"Scope Id","type":"string"},"scope_type":{"title":"Scope Type","type":"string"},"token_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Token Limit"},"updated_at":{"title":"Updated At","type":"string"}},"required":["id","scope_type","scope_id","provider_key_id","budget_id","name","max_budget","current_spend","reserved_spend","token_limit","current_tokens","reserved_tokens","request_limit","current_requests","reserved_requests","budget_duration_sec","reset_alignment","period_start","period_end","created_at","updated_at"],"title":"ScopedBudgetResponse","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/scoped-budgets":{"post":{"description":"Create a scoped budget.\n\nAnswers 404 when the scope names nothing, rather than creating a ceiling\nthat can never bind.","operationId":"scoped-budgets-create_scoped_budget","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScopedBudgetRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopedBudgetResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Create Scoped Budget","tags":["scoped-budgets"]}}}} ``` ## Get Scoped Budget > Get one scoped budget. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"ScopedBudgetResponse":{"description":"One scoped ceiling and its live counters.\n\nUnlike ``/api/v1/budgets``, the counters are the row's own: a scoped ceiling is\nenforced against ``current_spend + reserved_spend``, so there is no rollup\nover users to compute.\n\nEvery limit, along with ``budget_duration_sec`` and ``reset_alignment``, is\nread off the budget rather than stored here, and carried on the wire so a\ncaller can render a ceiling without fetching every budget to resolve one id.","properties":{"budget_duration_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Duration Sec"},"budget_id":{"title":"Budget Id","type":"string"},"created_at":{"title":"Created At","type":"string"},"current_requests":{"title":"Current Requests","type":"integer"},"current_spend":{"title":"Current Spend","type":"number"},"current_tokens":{"title":"Current Tokens","type":"integer"},"id":{"title":"Id","type":"string"},"max_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Budget"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period End"},"period_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Start"},"provider_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Key Id"},"request_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Limit"},"reserved_requests":{"title":"Reserved Requests","type":"integer"},"reserved_spend":{"title":"Reserved Spend","type":"number"},"reserved_tokens":{"title":"Reserved Tokens","type":"integer"},"reset_alignment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reset Alignment"},"scope_id":{"title":"Scope Id","type":"string"},"scope_type":{"title":"Scope Type","type":"string"},"token_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Token Limit"},"updated_at":{"title":"Updated At","type":"string"}},"required":["id","scope_type","scope_id","provider_key_id","budget_id","name","max_budget","current_spend","reserved_spend","token_limit","current_tokens","reserved_tokens","request_limit","current_requests","reserved_requests","budget_duration_sec","reset_alignment","period_start","period_end","created_at","updated_at"],"title":"ScopedBudgetResponse","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/scoped-budgets/{budget_id}":{"get":{"description":"Get one scoped budget.","operationId":"scoped-budgets-get_scoped_budget","parameters":[{"in":"path","name":"budget_id","required":true,"schema":{"title":"Budget Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopedBudgetResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get Scoped Budget","tags":["scoped-budgets"]}}}} ``` ## Update Scoped Budget > Relabel a ceiling, or point it at a different budget.\ > \ > The scope and the provider narrowing are not editable: changing either would\ > move the ceiling to a different identity while carrying its spend, which is\ > a delete and a create, not an update.\ > \ > There is no limit or period to set here any more. Both are properties of the\ > budget, so changing what a ceiling allows is either editing that budget,\ > which moves every ceiling naming it, or naming a different one. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"UpdateScopedBudgetRequest":{"description":"Request model for updating a scoped budget.","properties":{"budget_id":{"anyOf":[{"maxLength":255,"minLength":1,"type":"string"},{"type":"null"}],"title":"Budget Id"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"title":"Name"}},"title":"UpdateScopedBudgetRequest","type":"object"},"ScopedBudgetResponse":{"description":"One scoped ceiling and its live counters.\n\nUnlike ``/api/v1/budgets``, the counters are the row's own: a scoped ceiling is\nenforced against ``current_spend + reserved_spend``, so there is no rollup\nover users to compute.\n\nEvery limit, along with ``budget_duration_sec`` and ``reset_alignment``, is\nread off the budget rather than stored here, and carried on the wire so a\ncaller can render a ceiling without fetching every budget to resolve one id.","properties":{"budget_duration_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Duration Sec"},"budget_id":{"title":"Budget Id","type":"string"},"created_at":{"title":"Created At","type":"string"},"current_requests":{"title":"Current Requests","type":"integer"},"current_spend":{"title":"Current Spend","type":"number"},"current_tokens":{"title":"Current Tokens","type":"integer"},"id":{"title":"Id","type":"string"},"max_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Budget"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period End"},"period_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Start"},"provider_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Key Id"},"request_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Limit"},"reserved_requests":{"title":"Reserved Requests","type":"integer"},"reserved_spend":{"title":"Reserved Spend","type":"number"},"reserved_tokens":{"title":"Reserved Tokens","type":"integer"},"reset_alignment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reset Alignment"},"scope_id":{"title":"Scope Id","type":"string"},"scope_type":{"title":"Scope Type","type":"string"},"token_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Token Limit"},"updated_at":{"title":"Updated At","type":"string"}},"required":["id","scope_type","scope_id","provider_key_id","budget_id","name","max_budget","current_spend","reserved_spend","token_limit","current_tokens","reserved_tokens","request_limit","current_requests","reserved_requests","budget_duration_sec","reset_alignment","period_start","period_end","created_at","updated_at"],"title":"ScopedBudgetResponse","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/scoped-budgets/{budget_id}":{"patch":{"description":"Relabel a ceiling, or point it at a different budget.\n\nThe scope and the provider narrowing are not editable: changing either would\nmove the ceiling to a different identity while carrying its spend, which is\na delete and a create, not an update.\n\nThere is no limit or period to set here any more. Both are properties of the\nbudget, so changing what a ceiling allows is either editing that budget,\nwhich moves every ceiling naming it, or naming a different one.","operationId":"scoped-budgets-update_scoped_budget","parameters":[{"in":"path","name":"budget_id","required":true,"schema":{"title":"Budget Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateScopedBudgetRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopedBudgetResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Update Scoped Budget","tags":["scoped-budgets"]}}}} ``` ## Delete Scoped Budget > Delete a scoped budget.\ > \ > A request holding a reservation against it settles into nothing afterwards,\ > which is the right outcome: the ceiling no longer exists to be credited. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/scoped-budgets/{budget_id}":{"delete":{"description":"Delete a scoped budget.\n\nA request holding a reservation against it settles into nothing afterwards,\nwhich is the right outcome: the ceiling no longer exists to be credited.","operationId":"scoped-budgets-delete_scoped_budget","parameters":[{"in":"path","name":"budget_id","required":true,"schema":{"title":"Budget Id","type":"string"}}],"responses":{"204":{"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Delete Scoped Budget","tags":["scoped-budgets"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.otari.ai/otari/for-integrators/api-reference/scoped-budgets.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.