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

# Extra-Usage-Budget setzen

> Setze das Extra-Usage-Budget, das ein Mitglied nach dem enthaltenen Kontingent nutzen kann

Liste aktive menschliche Mitglieder, ändere einen Plan und setze das Extra-Usage-Budget über dem enthaltenen Kontingent. Beträge sind US-Dollar.

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. Diese API lädt niemanden ein und deaktiviert niemanden. Dafür nutzt du die [User Management API](https://docs.langdock.com/de/developer/user-management-api/user-management-overview.md).

## Basis-URL

```
https://api.langdock.com/billing/v1/bring-your-own-keys/users/{userId}/extra-usage-budget
```

> [!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
* `USER_MANAGEMENT_API` am selben Schlüssel, wenn du `email`, `name` oder einen E-Mail-Filter brauchst

## Extra-Usage-Budget setzen

`PUT /users/{userId}/extra-usage-budget` nimmt das Budget direkt entgegen. Es gibt kein Hüllenfeld.

```json theme={null}
{ "type": "limited", "amount": 30 }
```

`{ "type": "none" }` entfernt das Extra-Kontingent. `{ "type": "unlimited" }` entfernt die Zahlenobergrenze. Ein begrenzter Betrag darf null sein.

War das effektive Budget begrenzt und ist das neue effektive Budget höher oder unbegrenzt, wird die offene Nutzungslimit-Anfrage des Mitglieds geschlossen. Dasselbe oder ein niedrigeres Budget lässt die Anfrage offen. Ohne `usageRequestId` wird das Budget gespeichert, auch wenn das Schließen der Anfrage fehlschlägt.

Übergib `usageRequestId` in der Query, um genau diese Anfrage im selben Schreibzugriff zu beantworten. Das Budget wird nur gespeichert, wenn die Anfrage zu diesem Mitglied gehört, noch offen ist und das effektive Budget wie oben steigt. Sonst wird nichts geschrieben. Fehlt die Anfrage oder gehört sie nicht zu diesem Mitglied, kommt `404` mit `code` `NOT_FOUND`. Ist sie nicht mehr offen, kommt `409` mit `code` `USAGE_REQUEST_NOT_PENDING`. Steigt das Kontingent nicht, kommt `409` mit `code` `USAGE_REQUEST_NOT_ANSWERED`. Die Anfrage bleibt offen.

Die Antwort ist das Mitgliedsobjekt mit `extraUsagePeriodSpend` 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 PUT /billing/v1/bring-your-own-keys/users/{userId}/extra-usage-budget
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/users/{userId}/extra-usage-budget:
    parameters:
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/UsageRequestIdQuery'
    put:
      tags:
        - Users
      summary: Set user extra usage budget
      description: >-
        Raising the effective extra allowance resolves the pending usage
        request. Unchanged or lower allowances do not. The request body is the
        limit object directly; extraUsagePeriodSpend is null in the response.
      operationId: setByokBillingUserExtraUsage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ByokExtraUsageBudget'
      responses:
        '200':
          description: Updated resource. Spending is null; GET retrieves spending.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ByokUser'
        '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/UsageRequestConflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    UserId:
      in: path
      name: userId
      required: true
      schema:
        type: string
        format: uuid
    UsageRequestIdQuery:
      in: query
      name: usageRequestId
      schema:
        type: string
        format: uuid
      description: >-
        Optional pending usage request this write answers. The write is rejected
        with 404 unless the request belongs to this member, 409
        USAGE_REQUEST_NOT_PENDING if it is no longer pending, or 409
        USAGE_REQUEST_NOT_ANSWERED if the write does not increase the member's
        allowance (an unchanged or lower limit, or a plan the member already
        has); nothing is written in those cases. A real increase or upgrade
        resolves the member's pending request with or without this parameter.
  schemas:
    ByokExtraUsageBudget:
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - type
            - amount
          properties:
            type:
              type: string
              enum:
                - limited
            amount:
              type: number
              minimum: 0
        - type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - unlimited
        - type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - none
    ByokUser:
      type: object
      additionalProperties: false
      required:
        - id
        - plan
        - monthlyBudget
        - extraUsageBudget
        - extraUsagePeriodSpend
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
          description: Present only when the key also has the USER_MANAGEMENT_API scope.
        name:
          type: string
          nullable: true
          description: Present only when the key also has the USER_MANAGEMENT_API scope.
        plan:
          $ref: '#/components/schemas/ByokPlan'
        monthlyBudget:
          type: object
          additionalProperties: false
          required:
            - effective
          properties:
            effective:
              $ref: '#/components/schemas/ByokEffectiveLimit'
        extraUsageBudget:
          $ref: '#/components/schemas/ByokExtraUsageBudget'
        extraUsagePeriodSpend:
          type: number
          minimum: 0
          nullable: true
      description: >-
        USD. The highest plan/group monthly budget configures weekly and session
        allowances. Extra usage can start when those included allowances are
        exhausted. Spend is null when private and always null in mutation
        responses.
    ByokPlan:
      type: string
      enum:
        - standard
        - power_user
    ByokEffectiveLimit:
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - type
            - amount
            - source
          properties:
            type:
              type: string
              enum:
                - limited
            amount:
              type: number
              minimum: 0
            source:
              $ref: '#/components/schemas/ByokBudgetSource'
        - type: object
          additionalProperties: false
          required:
            - type
            - source
          properties:
            type:
              type: string
              enum:
                - unlimited
            source:
              $ref: '#/components/schemas/ByokBudgetSource'
    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
    UsageRequestNotPendingError:
      type: object
      additionalProperties: false
      required:
        - message
        - code
        - details
      properties:
        message:
          type: string
        code:
          type: string
          enum:
            - USAGE_REQUEST_NOT_PENDING
            - USAGE_REQUEST_NOT_ANSWERED
        details:
          type: object
          additionalProperties: false
          required:
            - status
          properties:
            status:
              type: string
              enum:
                - pending
                - resolved
                - dismissed
    ByokBudgetSource:
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - plan
        - type: object
          additionalProperties: false
          required:
            - type
            - groupId
            - groupName
          properties:
            type:
              type: string
              enum:
                - group
            groupId:
              type: string
              format: uuid
            groupName:
              type: string
  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'
    UsageRequestConflict:
      description: >-
        Workspace mode differs from the requested mode (BILLING_MODE_MISMATCH),
        the usage request is no longer pending (USAGE_REQUEST_NOT_PENDING,
        details.status holds its current status), or the write does not answer
        the named usage request (USAGE_REQUEST_NOT_ANSWERED).
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ModeMismatchError'
              - $ref: '#/components/schemas/UsageRequestNotPendingError'
    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.