> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Agent Budget

> Read one agent's monthly budget, budget mode, and spend

Read and update monthly agent budgets in US dollars. Use the `bring-your-own-keys` prefix for this workspace mode.

The calls use the workspace API key's `BILLING_API` scope. Writes run as the key's service account owner.

## Base URL

```
https://api.langdock.com/billing/v1/bring-your-own-keys/agents/{agentId}
```

> [!WARNING]
>
> **Dedicated deployments**
>
> Replace `api.langdock.com` with `<your-deployment-url>/api/public` in all requests.

## Prerequisites

* **API key** with the `BILLING_API` scope
* The key owner is a service account that has not been deleted and has an active Admin membership

```json theme={null}
{
  "id": "33333333-3333-4333-8333-333333333333",
  "name": "Contract reviewer",
  "budget": { "type": "limited", "amount": 40 },
  "budgetMode": "always",
  "budgetPeriodSpend": 18.7
}
```

`name` may be `null`. `budgetPeriodSpend` is `null` when the workspace hides per user spend.

When per user spend is hidden, agents that are not shared are left out of the list. Reading or updating one of those agents returns `404` and changes nothing. Shared agents stay in the list with `budgetPeriodSpend` set to `null`.

> [!NOTE]
>
> Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](https://docs.langdock.com/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices.md).


## OpenAPI

````yaml GET /billing/v1/bring-your-own-keys/agents/{agentId}
openapi: 3.0.0
info:
  title: Langdock API
  version: 3.0.0
servers:
  - url: https://api.langdock.com
    description: Production
security:
  - bearerAuth: []
paths:
  /billing/v1/bring-your-own-keys/agents/{agentId}:
    parameters:
      - $ref: '#/components/parameters/AgentId'
    get:
      tags:
        - Agents
      summary: Read an agent budget in USD
      operationId: getByokBillingAgent
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          $ref: '#/components/responses/ModeMismatch'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    AgentId:
      in: path
      name: agentId
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    Agent:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - budget
        - budgetMode
        - budgetPeriodSpend
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
        budget:
          $ref: '#/components/schemas/AgentBudget'
        budgetMode:
          type: string
          enum:
            - always
            - on_limit_hit
        budgetPeriodSpend:
          type: number
          minimum: 0
          nullable: true
      description: >-
        Monthly budget in mode currency, subject to workspace enforcement.
        always uses agent allowance; on_limit_hit uses it after the member
        allowance. Spend is null when user-level usage is hidden and always null
        on PATCH.
    AgentBudget:
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - type
            - amount
          properties:
            type:
              type: string
              enum:
                - limited
            amount:
              type: number
              minimum: 0
              exclusiveMinimum: true
        - type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - unlimited
        - type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - none
      description: >-
        Monthly budget in the mode currency. none follows workspace/member
        limits; unlimited keeps a separate budget without a numeric cap.
    Error:
      type: object
      additionalProperties: false
      required:
        - message
        - code
      properties:
        message:
          type: string
        code:
          type: string
        details:
          type: object
          additionalProperties: true
          description: >-
            Optional structured details specific to the error code, such as
            userIds for invalid bulk members.
    ModeMismatchError:
      type: object
      additionalProperties: false
      required:
        - message
        - code
        - details
      properties:
        message:
          type: string
        code:
          type: string
          enum:
            - BILLING_MODE_MISMATCH
        details:
          type: object
          additionalProperties: false
          required:
            - mode
          properties:
            mode:
              type: string
              enum:
                - ai-models-included
                - bring-your-own-keys
  responses:
    BadRequest:
      description: >-
        Invalid body/query, unknown fields, empty PATCH, invalid limit, invalid
        bulk member IDs, or a cursor outside this workspace (INVALID_CURSOR).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        Missing Billing scope, personal key, unavailable feature, missing active
        service-account Admin authority, or email filter without the
        USER_MANAGEMENT_API scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: >-
        Resource not in this workspace, inactive/non-human user, privacy-hidden
        agent, usage request not found for that member, or endpoint unavailable
        in this mode.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MethodNotAllowed:
      description: Unsupported HTTP method.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ModeMismatch:
      description: >-
        Workspace mode differs from the requested mode. details.mode identifies
        the workspace mode.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ModeMismatchError'
    TooManyRequests:
      description: API rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.