> For the complete documentation index, see [llms.txt](https://docs.nexos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexos.ai/gateway-api/budget-limit-management.md).
# Budget Limit Management
Manage company budget limits.
## List budget limits for a company. Deprecated, use /v1/companies/budget\_limits instead.
> Deprecated: Use /v1/companies/budget\_limits instead. Retrieve all budget limits for a specific company.
```json
{"openapi":"3.0.0","info":{"title":"Nexos AI Public API Production","version":"1.0.0"},"tags":[{"name":"Budget Limit Management","description":"Manage company budget limits."}],"servers":[{"url":"https://api.nexos.ai"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Authenticate by sending your nexos API key in the `X-Api-Key` header (e.g. `X-Api-Key: user-...` for a user key or `X-Api-Key: team-...` for a team key). This is an alternative to the `Authorization: Bearer` scheme. If both `X-Nexos-Key` and `X-Api-Key` are sent, `X-Nexos-Key` takes precedence."}},"responses":{"CompanyBudgetLimitListResponse":{"description":"A list of company budget limits.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CompanyBudgetLimit"}},"total":{"type":"integer"}}}}}}},"schemas":{"CompanyBudgetLimit":{"type":"object","properties":{"company_uuid":{"type":"string","description":"The UUID of the company."},"company_subscription_uuid":{"type":"string","description":"The UUID of the company subscription."},"target_type":{"type":"string","description":"The target type of the budget limit. Only team limits can be set.","enum":["company","team","user","api_key"]},"target_uuid":{"type":"string","description":"The UUID of the target (team, user or API key)."},"limit_type":{"deprecated":true,"type":"string","description":"Deprecated, pass company_subscription_uuid.","enum":["general","public-api"]},"is_renewed":{"type":"boolean","description":"Whether the budget limit is renewed periodically."},"value":{"type":"number","format":"double","description":"The budget limit value."},"allow_use_additional":{"type":"boolean","description":"Whether additional (extra) credits may be used once the limit is reached."},"max_extra_credits_value":{"type":"number","format":"double","nullable":true,"description":"The maximum amount of extra credits that may be used."},"created_at":{"type":"string","format":"date-time","description":"When the budget limit was created."},"updated_at":{"type":"string","format":"date-time","description":"When the budget limit was last updated."}},"required":["company_uuid","target_type","target_uuid","company_subscription_uuid","is_renewed","allow_use_additional","created_at","updated_at"]}}},"paths":{"/v1/companies/{companyId}/budget_limits":{"get":{"operationId":"get-company-budget-limits-by-id-v1","deprecated":true,"summary":"List budget limits for a company. Deprecated, use /v1/companies/budget_limits instead.","tags":["Budget Limit Management"],"description":"Deprecated: Use /v1/companies/budget_limits instead. Retrieve all budget limits for a specific company.","parameters":[{"name":"companyId","in":"path","required":true,"description":"The UUID of the company.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of items to return.","schema":{"type":"integer","format":"uint32","minimum":1}},{"name":"offset","in":"query","required":false,"description":"Number of items to skip.","schema":{"type":"integer","format":"uint32","minimum":0}}],"responses":{"200":{"$ref":"#/components/responses/CompanyBudgetLimitListResponse"},"500":{"description":"Server error."},"4XX":{"description":"Client error."}}}}}}
```
## List budget limits for a company
> Retrieve all budget limits for a specific company.
```json
{"openapi":"3.0.0","info":{"title":"Nexos AI Public API Production","version":"1.0.0"},"tags":[{"name":"Budget Limit Management","description":"Manage company budget limits."}],"servers":[{"url":"https://api.nexos.ai"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Authenticate by sending your nexos API key in the `X-Api-Key` header (e.g. `X-Api-Key: user-...` for a user key or `X-Api-Key: team-...` for a team key). This is an alternative to the `Authorization: Bearer` scheme. If both `X-Nexos-Key` and `X-Api-Key` are sent, `X-Nexos-Key` takes precedence."}},"responses":{"CompanyBudgetLimitListResponse":{"description":"A list of company budget limits.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CompanyBudgetLimit"}},"total":{"type":"integer"}}}}}}},"schemas":{"CompanyBudgetLimit":{"type":"object","properties":{"company_uuid":{"type":"string","description":"The UUID of the company."},"company_subscription_uuid":{"type":"string","description":"The UUID of the company subscription."},"target_type":{"type":"string","description":"The target type of the budget limit. Only team limits can be set.","enum":["company","team","user","api_key"]},"target_uuid":{"type":"string","description":"The UUID of the target (team, user or API key)."},"limit_type":{"deprecated":true,"type":"string","description":"Deprecated, pass company_subscription_uuid.","enum":["general","public-api"]},"is_renewed":{"type":"boolean","description":"Whether the budget limit is renewed periodically."},"value":{"type":"number","format":"double","description":"The budget limit value."},"allow_use_additional":{"type":"boolean","description":"Whether additional (extra) credits may be used once the limit is reached."},"max_extra_credits_value":{"type":"number","format":"double","nullable":true,"description":"The maximum amount of extra credits that may be used."},"created_at":{"type":"string","format":"date-time","description":"When the budget limit was created."},"updated_at":{"type":"string","format":"date-time","description":"When the budget limit was last updated."}},"required":["company_uuid","target_type","target_uuid","company_subscription_uuid","is_renewed","allow_use_additional","created_at","updated_at"]}}},"paths":{"/v1/companies/budget_limits":{"get":{"operationId":"get-company-budget-limits-v1","summary":"List budget limits for a company","tags":["Budget Limit Management"],"description":"Retrieve all budget limits for a specific company.","parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum number of items to return.","schema":{"type":"integer","format":"uint32","minimum":1}},{"name":"offset","in":"query","required":false,"description":"Number of items to skip.","schema":{"type":"integer","format":"uint32","minimum":0}}],"responses":{"200":{"$ref":"#/components/responses/CompanyBudgetLimitListResponse"},"500":{"description":"Server error."},"4XX":{"description":"Client error."}}}}}}
```
## Set the budget limit of a team
> Creates or updates the budget limit settings of a team. Only Company Owners can call this endpoint.\
> The call sets \`is\_renewed\`, \`allow\_use\_additional\` and \`max\_extra\_credits\_value\`. The limit value itself\
> cannot be changed here: an existing limit keeps its stored value and a newly created one starts at 0.\
> Workspace-wide and per-user limits cannot be changed.
```json
{"openapi":"3.0.0","info":{"title":"Nexos AI Public API Production","version":"1.0.0"},"tags":[{"name":"Budget Limit Management","description":"Manage company budget limits."}],"servers":[{"url":"https://api.nexos.ai"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Authenticate by sending your nexos API key in the `X-Api-Key` header (e.g. `X-Api-Key: user-...` for a user key or `X-Api-Key: team-...` for a team key). This is an alternative to the `Authorization: Bearer` scheme. If both `X-Nexos-Key` and `X-Api-Key` are sent, `X-Nexos-Key` takes precedence."}},"schemas":{"UpsertCompanyBudgetLimitRequest":{"type":"object","description":"Creates or updates the budget limit settings of a team. The limit value cannot be set here:\nan existing limit keeps its value, a newly created one starts at 0.\n","properties":{"target_uuid":{"type":"string","description":"The UUID of the team."},"is_renewed":{"type":"boolean","description":"Whether the budget limit is renewed periodically."},"allow_use_additional":{"type":"boolean","description":"Whether the key may use additional (extra) credits once its limit is reached."},"max_extra_credits_value":{"type":"number","format":"double","description":"The maximum amount of extra credits the key may use. When omitted, the currently stored cap is kept.\nAn existing cap can be replaced but not removed.\n","minimum":0,"maximum":100000000},"remove":{"type":"boolean","description":"Not supported. Removing a limit is rejected; omit this field or set it to false."}},"required":["target_uuid"]},"CompanyBudgetLimit":{"type":"object","properties":{"company_uuid":{"type":"string","description":"The UUID of the company."},"company_subscription_uuid":{"type":"string","description":"The UUID of the company subscription."},"target_type":{"type":"string","description":"The target type of the budget limit. Only team limits can be set.","enum":["company","team","user","api_key"]},"target_uuid":{"type":"string","description":"The UUID of the target (team, user or API key)."},"limit_type":{"deprecated":true,"type":"string","description":"Deprecated, pass company_subscription_uuid.","enum":["general","public-api"]},"is_renewed":{"type":"boolean","description":"Whether the budget limit is renewed periodically."},"value":{"type":"number","format":"double","description":"The budget limit value."},"allow_use_additional":{"type":"boolean","description":"Whether additional (extra) credits may be used once the limit is reached."},"max_extra_credits_value":{"type":"number","format":"double","nullable":true,"description":"The maximum amount of extra credits that may be used."},"created_at":{"type":"string","format":"date-time","description":"When the budget limit was created."},"updated_at":{"type":"string","format":"date-time","description":"When the budget limit was last updated."}},"required":["company_uuid","target_type","target_uuid","company_subscription_uuid","is_renewed","allow_use_additional","created_at","updated_at"]}},"responses":{"CompanyBudgetLimitResponse":{"description":"A company budget limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyBudgetLimit"}}}}}},"paths":{"/v1/companies/budget_limits":{"put":{"operationId":"put-company-budget-limits-v1","summary":"Set the budget limit of a team","tags":["Budget Limit Management"],"description":"Creates or updates the budget limit settings of a team. Only Company Owners can call this endpoint.\nThe call sets `is_renewed`, `allow_use_additional` and `max_extra_credits_value`. The limit value itself\ncannot be changed here: an existing limit keeps its stored value and a newly created one starts at 0.\nWorkspace-wide and per-user limits cannot be changed.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertCompanyBudgetLimitRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/CompanyBudgetLimitResponse"},"500":{"description":"Server error."},"4XX":{"description":"Client error."}}}}}}
```
## Set budget limits of teams in bulk
> Creates or updates the budget limit settings of up to 100 teams. Only Company Owners can call this endpoint.\
> For each item the call sets \`is\_renewed\`, \`allow\_use\_additional\` and \`max\_extra\_credits\_value\`. The limit value\
> itself cannot be changed here: an existing limit keeps its stored value and a newly created one starts at 0.\
> Nothing is written if any item is invalid.
```json
{"openapi":"3.0.0","info":{"title":"Nexos AI Public API Production","version":"1.0.0"},"tags":[{"name":"Budget Limit Management","description":"Manage company budget limits."}],"servers":[{"url":"https://api.nexos.ai"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Authenticate by sending your nexos API key in the `X-Api-Key` header (e.g. `X-Api-Key: user-...` for a user key or `X-Api-Key: team-...` for a team key). This is an alternative to the `Authorization: Bearer` scheme. If both `X-Nexos-Key` and `X-Api-Key` are sent, `X-Nexos-Key` takes precedence."}},"schemas":{"BulkUpsertCompanyBudgetLimitRequest":{"type":"object","description":"Updates the budget limit settings of several teams in one request. Nothing is written if any item is invalid.","properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/UpsertCompanyBudgetLimitRequest"}}},"required":["items"]},"UpsertCompanyBudgetLimitRequest":{"type":"object","description":"Creates or updates the budget limit settings of a team. The limit value cannot be set here:\nan existing limit keeps its value, a newly created one starts at 0.\n","properties":{"target_uuid":{"type":"string","description":"The UUID of the team."},"is_renewed":{"type":"boolean","description":"Whether the budget limit is renewed periodically."},"allow_use_additional":{"type":"boolean","description":"Whether the key may use additional (extra) credits once its limit is reached."},"max_extra_credits_value":{"type":"number","format":"double","description":"The maximum amount of extra credits the key may use. When omitted, the currently stored cap is kept.\nAn existing cap can be replaced but not removed.\n","minimum":0,"maximum":100000000},"remove":{"type":"boolean","description":"Not supported. Removing a limit is rejected; omit this field or set it to false."}},"required":["target_uuid"]},"CompanyBudgetLimit":{"type":"object","properties":{"company_uuid":{"type":"string","description":"The UUID of the company."},"company_subscription_uuid":{"type":"string","description":"The UUID of the company subscription."},"target_type":{"type":"string","description":"The target type of the budget limit. Only team limits can be set.","enum":["company","team","user","api_key"]},"target_uuid":{"type":"string","description":"The UUID of the target (team, user or API key)."},"limit_type":{"deprecated":true,"type":"string","description":"Deprecated, pass company_subscription_uuid.","enum":["general","public-api"]},"is_renewed":{"type":"boolean","description":"Whether the budget limit is renewed periodically."},"value":{"type":"number","format":"double","description":"The budget limit value."},"allow_use_additional":{"type":"boolean","description":"Whether additional (extra) credits may be used once the limit is reached."},"max_extra_credits_value":{"type":"number","format":"double","nullable":true,"description":"The maximum amount of extra credits that may be used."},"created_at":{"type":"string","format":"date-time","description":"When the budget limit was created."},"updated_at":{"type":"string","format":"date-time","description":"When the budget limit was last updated."}},"required":["company_uuid","target_type","target_uuid","company_subscription_uuid","is_renewed","allow_use_additional","created_at","updated_at"]}},"responses":{"CompanyBudgetLimitListResponse":{"description":"A list of company budget limits.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CompanyBudgetLimit"}},"total":{"type":"integer"}}}}}}}},"paths":{"/v1/companies/budget_limits/bulk":{"put":{"operationId":"put-company-budget-limits-bulk-v1","summary":"Set budget limits of teams in bulk","tags":["Budget Limit Management"],"description":"Creates or updates the budget limit settings of up to 100 teams. Only Company Owners can call this endpoint.\nFor each item the call sets `is_renewed`, `allow_use_additional` and `max_extra_credits_value`. The limit value\nitself cannot be changed here: an existing limit keeps its stored value and a newly created one starts at 0.\nNothing is written if any item is invalid.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpsertCompanyBudgetLimitRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/CompanyBudgetLimitListResponse"},"500":{"description":"Server error."},"4XX":{"description":"Client error."}}}}}}
```
---
# 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.nexos.ai/gateway-api/budget-limit-management.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.