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

# Nutzungslimit-Anfragen auflisten

> Liste Anfragen von Mitgliedern nach mehr Nutzung, gefiltert nach Status

Liste Nutzungslimit-Anfragen von Mitgliedern, lies eine Anfrage und lehne eine Anfrage ab, die noch offen ist. Es gibt keinen Webhook. Frage die Liste regelmäßig ab.

Um eine Anfrage zu genehmigen, erhöhst du den Plan oder das Extra-Usage-Budget dieses Mitglieds und übergibst `usageRequestId` an diesem Schreibzugriff. Siehe [Billing-Nutzer](https://docs.langdock.com/de/developer/billing-api/set-user-plan.md).

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

## Basis-URL

```
https://api.langdock.com/billing/v1/bring-your-own-keys/usage-requests
```

> [!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` oder `name` brauchst

`status` ist `pending`, `resolved` oder `dismissed`. Ohne Filter listest du jeden Status. Die Ergebnisse kommen mit den ältesten zuerst. `limit` ist standardmäßig 50 und höchstens 250. Gib `cursor` aus `nextCursor` zurück. Ein Cursor aus einem anderen Workspace gibt `400` mit `code` `INVALID_CURSOR` zurück. Eine Anfrage, die zwischen zwei Seiten beantwortet wird, lässt spätere Zeilen nicht aus.

Die Listenantwort ist `{ "usageRequests": [ ... ] }` und enthält `nextCursor` bis zur letzten Seite. Eine einzelne Anfrage kommt als Objekt zurück. Eine Anfrage außerhalb dieses Workspace gibt `404` mit `code` `NOT_FOUND` zurück.

Ausgeblendete Ausgaben pro Nutzer blenden diese Anfragen nicht aus. Ein Mitglied, das ein Limit erreicht und nicht anfragt, steht nicht in dieser Liste.

Zum Abfragen rufst du `GET /usage-requests?status=pending` auf und überspringst Anfragen, die du schon bearbeitet hast.

> [!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/usage-requests
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/usage-requests:
    get:
      tags:
        - Usage requests
      summary: List usage requests
      description: >-
        Oldest first. Poll with status=pending to process new requests. email
        and name require the USER_MANAGEMENT_API scope.
      operationId: listByokBillingUsageRequests
      parameters:
        - $ref: '#/components/parameters/UsageRequestStatus'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/UuidCursor'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageRequestList'
        '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:
    UsageRequestStatus:
      in: query
      name: status
      schema:
        type: string
        enum:
          - pending
          - resolved
          - dismissed
      description: Only return requests with this status.
    Limit:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 250
        default: 50
    UuidCursor:
      in: query
      name: cursor
      schema:
        type: string
        format: uuid
      description: Use nextCursor from the preceding page.
  schemas:
    UsageRequestList:
      type: object
      additionalProperties: false
      required:
        - usageRequests
      properties:
        usageRequests:
          type: array
          items:
            $ref: '#/components/schemas/UsageRequest'
        nextCursor:
          type: string
          format: uuid
    UsageRequest:
      type: object
      additionalProperties: false
      required:
        - id
        - userId
        - status
        - createdAt
        - resolvedAt
        - resolution
        - resolvedByUserId
      properties:
        id:
          type: string
          format: uuid
        userId:
          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.
        status:
          type: string
          enum:
            - pending
            - resolved
            - dismissed
        createdAt:
          type: string
          format: date-time
        resolvedAt:
          type: string
          format: date-time
          nullable: true
        resolution:
          type: string
          nullable: true
          enum:
            - increased_limit
            - upgraded_plan
            - dismissed
            - null
          description: How the request was answered; null while pending.
        resolvedByUserId:
          type: string
          format: uuid
          nullable: true
          description: Admin or service account that answered the request.
    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.