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

# Nutzer abrufen

> Lies Plan, effektives enthaltenes Budget und Extra-Usage-Budget eines Mitglieds

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}
```

> [!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

Ein Mitgliedsobjekt enthält `email` und `name` nur, wenn der Schlüssel auch `USER_MANAGEMENT_API` hat. Ohne den Scope fehlen die Felder. `name` kann `null` sein, wenn es enthalten ist.

```json theme={null}
{
  "id": "11111111-1111-4111-8111-111111111111",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "plan": "power_user",
  "monthlyBudget": {
    "effective": {
      "type": "limited",
      "amount": 120,
      "source": { "type": "plan" }
    }
  },
  "extraUsageBudget": { "type": "limited", "amount": 30 },
  "extraUsagePeriodSpend": 12.4
}
```

`monthlyBudget.effective` ist das enthaltene Monatsbudget. Es ist der höhere Wert aus Planbudget und Gruppenbudgets. Unbegrenzt schlägt begrenzt. Bei gleichem Betrag gewinnt der Plan gegen eine Gruppe. Setzen zwei Gruppen denselben Betrag, ist die Quelle die Gruppe, deren Name zuerst kommt. `source` ist `plan` oder `group` mit `groupId` und `groupName`.

Dieses Monatsbudget setzt das Wochenkontingent (Monat geteilt durch 4) und das Session-Kontingent (Woche geteilt durch 3). `extraUsageBudget` ist das Kontingent, nachdem diese Fenster aufgebraucht sind. Es ist `none`, `unlimited` oder `limited`.

`extraUsagePeriodSpend` misst diese Extra Usage. Der Wert ist `null`, wenn der Workspace die Ausgaben pro Nutzer ausblendet. Wer kein aktives menschliches Mitglied ist, gibt `404` zurück.

> [!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/users/{userId}
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}:
    parameters:
      - $ref: '#/components/parameters/UserId'
    get:
      tags:
        - Users
      summary: Read a user
      operationId: getByokBillingUser
      responses:
        '200':
          description: Successful response.
          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/ModeMismatch'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    UserId:
      in: path
      name: userId
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    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'
    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
    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
    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'
    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.