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

# Set User Extra Usage Budget

> Set the extra usage budget a member can use after the included allowance

List active human members, change a plan, and set the extra usage budget beyond the included allowance. Amounts are US dollars.

The calls use the workspace API key's `BILLING_API` scope. Writes run as the key's service account owner. This API does not invite or deactivate members. Use the [User Management API](https://docs.langdock.com/en/developer/user-management-api/user-management-overview.md) for that.

## Base URL

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

> [!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
* `USER_MANAGEMENT_API` on the same key when you need `email`, `name`, or an email filter

## Set an extra usage budget

`PUT /users/{userId}/extra-usage-budget` takes the budget directly. There is no wrapper field.

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

`{ "type": "none" }` removes the extra allowance. `{ "type": "unlimited" }` removes the numeric cap. A limited amount may be zero.

If the effective budget was limited and the new effective budget is higher or unlimited, the member's pending usage request is closed. The same budget or a lower one leaves the request open. Without `usageRequestId`, the budget is saved even if closing the request fails.

Pass `usageRequestId` as a query parameter to answer that request in the same write. The budget is kept only when the request belongs to this member, is still pending, and the effective budget rises as described above. Otherwise nothing is written. A missing request, or one that is not this member's, returns `404` with `code` `NOT_FOUND`. A request that is no longer pending returns `409` with `code` `USAGE_REQUEST_NOT_PENDING`. A change that does not raise the allowance returns `409` with `code` `USAGE_REQUEST_NOT_ANSWERED`. The request stays pending.

The response is the member object with `extraUsagePeriodSpend` 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 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.