> ## 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.

# Agent-Budget abrufen

> Lies Monatsbudget, Budgetmodus und Ausgaben eines Agenten

Lies und ändere monatliche Agent-Budgets in US-Dollar. Für diesen Workspace-Modus nutzt du das Präfix `bring-your-own-keys`.

Die Aufrufe laufen über den `BILLING_API` Scope des Workspace-API-Schlüssels. Schreibzugriffe laufen als der Service Account, dem der Schlüssel gehört.

## Basis-URL

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

> [!WARNING]
>
> **Dedicated Deployments**
>
> Ersetze `api.langdock.com` durch `<your-deployment-url>/api/public` in allen Anfragen.

## Voraussetzungen

* **API-Schlüssel** mit dem Scope `BILLING_API`
* Der Besitzer ist ein Service Account, der nicht gelöscht ist und eine aktive Admin-Mitgliedschaft hat

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

`name` kann `null` sein. `budgetPeriodSpend` ist `null`, wenn der Workspace die Ausgaben pro Nutzer ausblendet.

Sind die Ausgaben pro Nutzer ausgeblendet, fehlen Agenten, die nicht geteilt sind, in der Liste. Einen solchen Agenten zu lesen oder zu ändern gibt `404` zurück und ändert nichts. Geteilte Agenten bleiben in der Liste, mit `budgetPeriodSpend` auf `null`.

> [!NOTE]
>
> Langdock blockiert bewusst Browser-basierte Anfragen, um deinen API-Schlüssel zu schützen und die Sicherheit deiner Anwendungen zu gewährleisten. Weitere Informationen findest du in unserem Guide zu [Best Practices für API-Schlüssel](https://docs.langdock.com/de/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.