> ## Documentation Index > Fetch the complete documentation index at: https://docs.querying.ai/llms.txt > Use this file to discover all available pages before exploring further. # Unterkonten: Schlüssel, Limits und Verbrauch pro Endkunde > Geben Sie jedem Ihrer Kunden eigene API-Schlüssel, ein Credit-Limit und ein Parallelitätslimit, halten Sie die Ergebnisse getrennt und lesen Sie den Verbrauch pro Kunde ab. Sie erhalten eine Rechnung. Wenn Sie querying.ai in Ihrem eigenen Produkt einsetzen, legen Sie für jeden Kunden ein Unterkonto an. Ein Unterkonto hat eigene API-Schlüssel, Limits, Tasks, Batches und Monitore. Seine Credits kommen aus Ihrem Guthaben, und die Verbrauchs-Endpunkte zeigen, was Sie jedem Kunden berechnen. ## So funktioniert ein Unterkonto * **Eigene Schlüssel und Ergebnisse.** Ein Unterkonto-Schlüssel sendet und liest Tasks, Batches und Monitore wie jeder andere Schlüssel und sieht nur seine eigene Arbeit. Ein mit dem Schlüssel von Acme erstellter Task liefert dem Schlüssel von Globex und Ihren eigenen Schlüsseln `404`. * **Ihre Credits.** Seine Tasks werden Ihrem Guthaben belastet. Ein Unterkonto hat kein eigenes Guthaben, daher erhalten seine Schlüssel bei `GET /v1/credits` und `GET /v1/usage` `403 SUB_ACCOUNT_FORBIDDEN`. * **Ihre Kapazität.** Das Parallelitätslimit Ihres Plans oder Vertrags gilt für Ihre eigenen Tasks und alle Unterkonten zusammen; Unterkonten bringen also nie zusätzliche Kapazität. `GET /v1/async/status` zählt diese gemeinsame Warteschlange mit Ihrem Schlüssel, und der Schlüssel eines Unterkontos erhält dort `403 SUB_ACCOUNT_FORBIDDEN`. * **Ihre Monitor-Limits.** Das Limit `monitors` aus `GET /v1/monitors/capabilities` zählt Ihre Monitore und die aller Unterkonten zusammen, und die Limits `prompts` und `tasksPerRun` gelten für die Monitore eines Unterkontos wie für Ihre. * **Eigene Limits.** `monthlyCreditLimit` begrenzt, was ihm in einem UTC-Kalendermonat berechnet werden kann. `concurrencyLimit` begrenzt seine wartenden und laufenden Tasks innerhalb Ihres Limits. Beide sind optional. * **Eine Ebene.** Ein Unterkonto kann keine Unterkonten haben. Alarm-E-Mails seiner Monitore gehen an die Administratoren Ihres Kontos. ## Wer Unterkonten verwalten kann Rufen Sie die Endpunkte `/v1/sub-accounts` mit einem Ihrer eigenen API-Schlüssel ohne Engine-Beschränkung und ohne tägliches Credit-Limit auf. Jeder andere Schlüssel erhält `403 SUB_ACCOUNT_FORBIDDEN`, weil ein eingeschränkter Schlüssel sonst Schlüssel ohne seine eigenen Einschränkungen ausstellen könnte. Die Schlüssel eines Unterkontos erhalten denselben Fehler. ```json theme={"theme":"css-variables"} { "success": false, "error": { "code": "SUB_ACCOUNT_FORBIDDEN", "message": "Managing sub-accounts needs an API key without an engine scope or a daily credit limit", "timestamp": "2026-10-19T09:00:00.000Z" } } ``` ## Unterkonto und Schlüssel anlegen ```bash theme={"theme":"css-variables"} curl -X POST https://api.querying.ai/v1/sub-accounts \ -H "Authorization: Bearer $QUERYING_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Acme", "externalId": "cust_acme", "monthlyCreditLimit": 200000, "concurrencyLimit": 50}' ``` Die Antwort ist `201`: ```json theme={"theme":"css-variables"} { "success": true, "data": { "id": "0199d2a4-5b10-7000-8000-000000000001", "name": "Acme", "externalId": "cust_acme", "status": "active", "monthlyCreditLimit": 200000, "concurrencyLimit": 50, "createdAt": "2026-10-09T09:00:00.000Z", "suspendedAt": null, "usage": { "month": "2026-10", "credits": 0, "tasks": 0, "reservedCredits": 0 } } } ``` | Feld | Pflicht | Beschreibung | | - | - | - | | `name` | Ja | 1–128 Zeichen. | | `externalId` | Nein | Ihre ID für diesen Kunden, 1–128 Zeichen, eindeutig unter Ihren Unterkonten. Ein zweites Anlegen mit demselben Wert ergibt `409 SUB_ACCOUNT_EXISTS`, sodass eine Wiederholung nie ein Duplikat erzeugt. Das bestehende finden Sie mit `GET /v1/sub-accounts?externalId=cust_acme`. | | `monthlyCreditLimit` | Nein | 0,01 bis 20.000.000 Credits, höchstens zwei Dezimalstellen. Weglassen oder `null` senden für keine Obergrenze. | | `concurrencyLimit` | Nein | Ganzzahl von 1 bis 100.000. Weglassen oder `null` senden für keine Obergrenze. | Jedes andere Feld ergibt `400 VALIDATION_ERROR`, sodass ein falsch geschriebenes Limit einen Kunden nie unbegrenzt lässt. Stellen Sie dem Unterkonto dann einen Schlüssel aus: ```bash theme={"theme":"css-variables"} curl -X POST https://api.querying.ai/v1/sub-accounts/$SUB_ACCOUNT_ID/keys \ -H "Authorization: Bearer $QUERYING_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "production", "allowedTaskTypes": ["CHATGPT", "GEMINI"]}' ``` ```json theme={"theme":"css-variables"} { "success": true, "data": { "id": "b7e4c1a2-...", "name": "production", "keyPrefix": "vt_3f9a1c2b", "createdAt": "2026-10-09T09:01:00.000Z", "allowedTaskTypes": ["CHATGPT", "GEMINI"], "dailyCreditLimit": null, "expiresAt": null, "key": "vt_3f9a1c2b..." } } ``` > [!WARNING] > > `key` erscheint nur in dieser Antwort. Speichern Sie ihn jetzt; er wird nie wieder angezeigt. Ein Schlüssel hat dieselben optionalen Einstellungen wie ein Dashboard-Schlüssel: `name` (1–64 Zeichen, Standard `default`), `allowedTaskTypes`, `dailyCreditLimit` und `expiresAt` (5 Minuten bis 2 Jahre in der Zukunft). Senden Sie keinen Body für einen Schlüssel ohne Einschränkungen. Ein Unterkonto kann bis zu 5 aktive Schlüssel haben; widerrufene und abgelaufene zählen nicht. Ein sechster ergibt `409 KEY_LIMIT`. Widerrufen Sie zuerst einen. Der Schlüssel Ihres Kunden funktioniert an jedem Endpunkt wie jeder andere Schlüssel: ```bash theme={"theme":"css-variables"} curl -X POST https://api.querying.ai/v1/async/task \ -H "Authorization: Bearer $ACME_KEY" \ -H "Content-Type: application/json" \ -d '{"taskType": "CHATGPT", "payload": {"prompt": "best project management software", "country": "US"}}' ``` ## Schlüssel verwalten `GET /v1/sub-accounts/{id}/keys` listet jeden Schlüssel, den das Unterkonto je hatte, neueste zuerst, einschließlich widerrufener und abgelaufener. Prüfen Sie `revokedAt` und `expiresAt`, um die aktiven Schlüssel zu finden. ```json theme={"theme":"css-variables"} { "success": true, "data": { "keys": [ { "id": "b7e4c1a2-...", "name": "production", "keyPrefix": "vt_3f9a1c2b", "createdAt": "2026-10-09T09:01:00.000Z", "revokedAt": null, "lastUsedAt": "2026-10-19T08:58:12.000Z", "allowedTaskTypes": ["CHATGPT", "GEMINI"], "dailyCreditLimit": null, "expiresAt": null }, { "id": "4d2a9e10-...", "name": "staging", "keyPrefix": "vt_8c01d5e7", "createdAt": "2026-10-01T12:00:00.000Z", "revokedAt": "2026-10-09T09:02:00.000Z", "lastUsedAt": "2026-10-08T17:40:03.000Z", "allowedTaskTypes": [], "dailyCreditLimit": null, "expiresAt": null } ] } } ``` `DELETE /v1/sub-accounts/{id}/keys/{keyId}` widerruft einen Schlüssel und gibt `{"success": true, "data": {"revoked": ""}}` zurück. Ein bereits widerrufener Schlüssel oder einer, der nicht zum Unterkonto gehört, ergibt `404 NOT_FOUND`. ## Limits | Limit | Zählt | Bei Erreichen | | - | - | - | | `monthlyCreditLimit` | Die Belastungen des Unterkontos in diesem UTC-Monat plus die von seinen noch laufenden Tasks reservierten Credits | `429 SUB_ACCOUNT_CREDIT_LIMIT` | | `concurrencyLimit` | Die wartenden und laufenden Tasks des Unterkontos | `429 PLAN_CONCURRENCY_LIMIT`, `details.source: "sub_account"` | | Limit Ihres Plans oder Vertrags | Ihre Tasks und die aller Unterkonten | `429 PLAN_CONCURRENCY_LIMIT`, `details.source: "plan"` oder `"contract"` | | Ihr Guthaben | Alle | `402 INSUFFICIENT_CREDITS` | Abgelehnt wird nur das Unterkonto, das sein eigenes Limit erreicht hat; Ihre anderen Kunden laufen weiter. Ein erhöhtes Limit gilt ab der nächsten Anfrage. ```json theme={"theme":"css-variables"} { "success": false, "error": { "code": "SUB_ACCOUNT_CREDIT_LIMIT", "message": "Sub-account monthly credit limit 200000 would be exceeded (199998 used, 3 needed)", "details": { "limit": 200000, "used": 199998, "needed": 3, "retryAfterSec": 1814400 }, "timestamp": "2026-10-09T09:00:00.000Z" } } ``` `retryAfterSec` zählt bis zum Beginn des nächsten UTC-Monats, wenn die Monatszählung neu beginnt. Die kontoweiten Limits finden Sie unter [Credits und Limits](/de/concepts/credits-and-limits.md). ## Ein Unterkonto jetzt prüfen `GET /v1/sub-accounts/{id}` liefert das Unterkonto mit dem Verbrauch dieses Monats und `activeTasks`, der Zahl seiner gerade wartenden oder laufenden Tasks. Vergleichen Sie sie mit `concurrencyLimit`, um zu sehen, wie nah der Kunde an seiner Obergrenze ist. ```json theme={"theme":"css-variables"} { "success": true, "data": { "id": "0199d2a4-5b10-7000-8000-000000000001", "name": "Acme", "externalId": "cust_acme", "status": "active", "monthlyCreditLimit": 200000, "concurrencyLimit": 50, "createdAt": "2026-10-09T09:00:00.000Z", "suspendedAt": null, "usage": { "month": "2026-10", "credits": 48211.5, "tasks": 39870, "reservedCredits": 37.5 }, "activeTasks": 31 } } ``` Die Werte oben sind ein Beispiel. In `usage` sind `credits` und `tasks` die Belastungen dieses UTC-Monats, und `reservedCredits` ist von noch laufenden Tasks reserviert. ## Verbrauch und Abrechnung Jede Belastung erscheint auch in Ihrem eigenen Abrechnungsjournal; diese Endpunkte schlüsseln sie nach Kunde auf. Fehlgeschlagene Tasks werden nie berechnet und nie gezählt. Credit-Beträge haben bis zu zwei Dezimalstellen. * `GET /v1/sub-accounts` listet Ihre Unterkonten, älteste zuerst, jeweils mit dem `usage` dieses Monats. Blättern Sie mit `limit` (Standard 100, höchstens 1.000) und geben Sie `nextCursor` als `cursor` zurück. * `GET /v1/sub-accounts/usage` summiert jedes Unterkonto über einen Bereich von UTC-Daten. * `GET /v1/sub-accounts/{id}/usage` liefert die Belastungen eines Unterkontos pro Tag und Engine. Beide Verbrauchs-Endpunkte nehmen `from` und `to` als `YYYY-MM-DD`, jeweils einschließlich. `from` ist standardmäßig der Erste des aktuellen UTC-Monats und `to` heute; ein Bereich umfasst höchstens 366 Tage. ### Alle Unterkonten ```bash theme={"theme":"css-variables"} curl "https://api.querying.ai/v1/sub-accounts/usage?from=2026-10-01&to=2026-10-31" \ -H "Authorization: Bearer $QUERYING_API_KEY" ``` Zum Beispiel: ```json theme={"theme":"css-variables"} { "success": true, "data": { "from": "2026-10-01", "to": "2026-10-31", "credits": 184200, "tasks": 61400, "subAccounts": [ { "id": "0199d2a4-5b10-7000-8000-000000000001", "name": "Acme", "externalId": "cust_acme", "credits": 150000, "tasks": 50000 }, { "id": "0199d2a4-6c20-7000-8000-000000000002", "name": "Globex", "externalId": "cust_globex", "credits": 34200, "tasks": 11400 } ] } } ``` Die Unterkonten sind nach Größe absteigend sortiert. Ein Unterkonto ohne Belastung im Bereich wird ausgelassen. ### Ein Unterkonto ```bash theme={"theme":"css-variables"} curl "https://api.querying.ai/v1/sub-accounts/$SUB_ACCOUNT_ID/usage?from=2026-10-08&to=2026-10-09" \ -H "Authorization: Bearer $QUERYING_API_KEY" ``` Zum Beispiel: ```json theme={"theme":"css-variables"} { "success": true, "data": { "id": "0199d2a4-5b10-7000-8000-000000000001", "from": "2026-10-08", "to": "2026-10-09", "credits": 3062.5, "tasks": 2950, "days": [ { "date": "2026-10-08", "taskType": "CHATGPT", "credits": 1500, "tasks": 1500 }, { "date": "2026-10-08", "taskType": "GEMINI", "credits": 312.5, "tasks": 250 }, { "date": "2026-10-08", "taskType": "OTHER", "credits": 50, "tasks": 0 }, { "date": "2026-10-09", "taskType": "CHATGPT", "credits": 1200, "tasks": 1200 } ] } } ``` * `credits` und `tasks` auf oberster Ebene sind die Summen von `days`. * `days` hat eine Zeile pro UTC-Datum und Engine mit einer Belastung, sortiert nach Datum, dann nach `taskType`. Tage ohne Belastung haben keine Zeile. * `taskType: "OTHER"` ist eine Belastung, die kein Task ist, etwa das [Lesen der Wettbewerber](/de/monitors.md#kosten-und-zeitplan) eines Monitors. Sie erhöht die Credits, aber nicht `tasks`. ## Sperren und entsperren ```bash theme={"theme":"css-variables"} curl -X PATCH https://api.querying.ai/v1/sub-accounts/$SUB_ACCOUNT_ID \ -H "Authorization: Bearer $QUERYING_API_KEY" \ -H "Content-Type: application/json" \ -d '{"status": "suspended"}' ``` * Seine Schlüssel liefern innerhalb von fünf Sekunden `401`. * Seine Monitore laufen nicht mehr, und noch nicht gestartete Batch-Elemente enden als `API_KEY_INACTIVE`. * Bereits wartende oder laufende Tasks werden abgeschlossen und berechnet. `{"status": "active"}` stellt seine Schlüssel und Monitore wieder her. Jeder Monitor läuft bei der Rückkehr einmal, statt verpasste Läufe nachzuholen. Derselbe `PATCH` ändert `name`, `externalId`, `monthlyCreditLimit` und `concurrencyLimit`; `null` entfernt ein Limit oder die `externalId`. Ein Unterkonto kann nicht gelöscht werden; sperren Sie es stattdessen. ## Fehler | Status | Code | Ursache | | - | - | - | | `400` | `VALIDATION_ERROR` | Ungültiges JSON, ein unbekanntes Feld, ein Wert außerhalb des zulässigen Bereichs oder ein ungültiger Verbrauchszeitraum. | | `403` | `SUB_ACCOUNT_FORBIDDEN` | Der Schlüssel hat eine Engine-Beschränkung oder ein tägliches Credit-Limit oder gehört zu einem Unterkonto. | | `404` | `NOT_FOUND` | Kein Unterkonto mit dieser ID unter Ihren oder kein aktiver Schlüssel mit dieser ID. | | `409` | `SUB_ACCOUNT_EXISTS` | Ein anderes Unterkonto hat diese `externalId` bereits. | | `409` | `KEY_LIMIT` | Das Unterkonto hat bereits 5 aktive Schlüssel. | ## Endpunkte | Methode und Pfad | Zweck | | - | - | | [`POST /v1/sub-accounts`](/de/api-reference/sub-accounts/create-sub-account) | Anlegen | | [`GET /v1/sub-accounts`](/de/api-reference/sub-accounts/list-sub-accounts) | Auflisten, mit `externalId`, `limit` und `cursor` | | [`GET /v1/sub-accounts/{id}`](/de/api-reference/sub-accounts/get-sub-account) | Ein Unterkonto, mit `activeTasks` | | [`PATCH /v1/sub-accounts/{id}`](/de/api-reference/sub-accounts/update-sub-account) | Einstellungen ändern, sperren oder entsperren | | [`GET /v1/sub-accounts/usage`](/de/api-reference/sub-accounts/list-usage) | Summen pro Unterkonto | | [`GET /v1/sub-accounts/{id}/usage`](/de/api-reference/sub-accounts/get-usage) | Ein Unterkonto pro Tag und Engine | | [`GET /v1/sub-accounts/{id}/keys`](/de/api-reference/sub-accounts/list-keys) | Seine Schlüssel auflisten, einschließlich widerrufener und abgelaufener | | [`POST /v1/sub-accounts/{id}/keys`](/de/api-reference/sub-accounts/issue-key) | Einen Schlüssel ausstellen | | [`DELETE /v1/sub-accounts/{id}/keys/{keyId}`](/de/api-reference/sub-accounts/revoke-key) | Einen Schlüssel widerrufen | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.