> 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

> 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: nexos-...` for a user key or `X-Api-Key: nexos-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."},"target_type":{"type":"string","description":"The target type of the budget limit. Only team or user are supported for new limits.","enum":["company","team","user"]},"target_uuid":{"type":"string","description":"The UUID of the target (team or user)."},"limit_type":{"type":"string","description":"The type of budget limit.","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."},"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","limit_type","is_renewed","created_at","updated_at"]}}},"paths":{"/v1/companies/{companyId}/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":"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."}}}}}}
```

## Upsert a budget limit

> Create or update a budget limit for a 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: nexos-...` for a user key or `X-Api-Key: nexos-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","properties":{"target_type":{"type":"string","description":"The target type of the budget limit (only team or user are supported).","enum":["team","user"]},"target_uuid":{"type":"string","description":"The UUID of the target (team or user). Empty string for default budget"},"limit_type":{"type":"string","description":"The type of budget limit.","enum":["general","public-api"]},"is_renewed":{"type":"boolean","description":"Whether the budget limit is renewed periodically."},"value":{"type":"integer","format":"int64","description":"The budget limit value.","nullable":true}},"required":["target_type","target_uuid","limit_type","is_renewed","value"]},"CompanyBudgetLimit":{"type":"object","properties":{"company_uuid":{"type":"string","description":"The UUID of the company."},"target_type":{"type":"string","description":"The target type of the budget limit. Only team or user are supported for new limits.","enum":["company","team","user"]},"target_uuid":{"type":"string","description":"The UUID of the target (team or user)."},"limit_type":{"type":"string","description":"The type of budget limit.","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."},"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","limit_type","is_renewed","created_at","updated_at"]}},"responses":{"CompanyBudgetLimitResponse":{"description":"A single company budget limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyBudgetLimit"}}}}}},"paths":{"/v1/companies/{companyId}/budget_limits":{"put":{"operationId":"put-company-budget-limits-v1","summary":"Upsert a budget limit","tags":["Budget Limit Management"],"description":"Create or update a budget limit for a company.","parameters":[{"name":"companyId","in":"path","required":true,"description":"The UUID of the company.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertCompanyBudgetLimitRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/CompanyBudgetLimitResponse"},"400":{"description":"Invalid request data."}}}}}}
```

## Delete a budget limit

> Delete a specific budget limit for a 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: nexos-...` for a user key or `X-Api-Key: nexos-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":{"DeleteCompanyBudgetLimitRequest":{"type":"object","properties":{"target_type":{"type":"string","description":"The target type of the budget limit (only team or user are supported).","enum":["team","user"]},"target_uuid":{"type":"string","description":"The UUID of the target (team or user)."},"limit_type":{"type":"string","description":"The type of budget limit.","enum":["general","public-api"]}},"required":["target_type","limit_type","target_uuid"]}}},"paths":{"/v1/companies/{companyId}/budget_limits":{"delete":{"operationId":"delete-company-budget-limits-v1","summary":"Delete a budget limit","tags":["Budget Limit Management"],"description":"Delete a specific budget limit for a company.","parameters":[{"name":"companyId","in":"path","required":true,"description":"The UUID of the company.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteCompanyBudgetLimitRequest"}}}},"responses":{"204":{"description":"Budget limit deleted successfully."},"404":{"description":"Budget limit not found."}}}}}}
```

## Bulk upsert and delete budget limits

> Apply many budget-limit changes for a company in a single call. Each item is upserted by default; items with \`remove: true\` delete the matching row identified by \`(company\_uuid, target\_type, target\_uuid, limit\_type)\`.

```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: nexos-...` for a user key or `X-Api-Key: nexos-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","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BulkUpsertCompanyBudgetLimitItem"}}},"required":["items"]},"BulkUpsertCompanyBudgetLimitItem":{"type":"object","properties":{"target_type":{"type":"string","description":"The target type of the budget limit (only team or user are supported).","enum":["team","user"]},"target_uuid":{"type":"string","description":"The UUID of the target (team or user). Empty string for default budget."},"limit_type":{"type":"string","description":"The type of budget limit.","enum":["general","public-api"]},"is_renewed":{"type":"boolean","description":"Whether the budget limit is renewed periodically."},"value":{"type":"integer","format":"int64","description":"The budget limit value. Ignored when remove is true."},"remove":{"type":"boolean","description":"When true, the matching row is deleted instead of upserted."}},"required":["target_type","target_uuid","limit_type","is_renewed"]},"CompanyBudgetLimit":{"type":"object","properties":{"company_uuid":{"type":"string","description":"The UUID of the company."},"target_type":{"type":"string","description":"The target type of the budget limit. Only team or user are supported for new limits.","enum":["company","team","user"]},"target_uuid":{"type":"string","description":"The UUID of the target (team or user)."},"limit_type":{"type":"string","description":"The type of budget limit.","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."},"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","limit_type","is_renewed","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/{companyId}/budget_limits/bulk":{"put":{"operationId":"put-company-budget-limits-bulk-v1","summary":"Bulk upsert and delete budget limits","tags":["Budget Limit Management"],"description":"Apply many budget-limit changes for a company in a single call. Each item is upserted by default; items with `remove: true` delete the matching row identified by `(company_uuid, target_type, target_uuid, limit_type)`.","parameters":[{"name":"companyId","in":"path","required":true,"description":"The UUID of the company.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpsertCompanyBudgetLimitRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/CompanyBudgetLimitListResponse"},"400":{"description":"Invalid request data."}}}}}}
```


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexos.ai/gateway-api/budget-limit-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.