Unterkonten: Schlüssel, Limits und Verbrauch pro Endkunde

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.

{
  "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

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:

{
  "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:

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"]}'

{
  "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..."
  }
}

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:

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.

{
  "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": "<keyId>"}} 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.

{
  "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.

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.

{
  "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

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:

{
  "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

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:

{
  "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 eines Monitors. Sie erhöht die Credits, aber nicht tasks.

Sperren und entsperren

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`	Anlegen
`GET /v1/sub-accounts`	Auflisten, mit `externalId`, `limit` und `cursor`
`GET /v1/sub-accounts/{id}`	Ein Unterkonto, mit `activeTasks`
`PATCH /v1/sub-accounts/{id}`	Einstellungen ändern, sperren oder entsperren
`GET /v1/sub-accounts/usage`	Summen pro Unterkonto
`GET /v1/sub-accounts/{id}/usage`	Ein Unterkonto pro Tag und Engine
`GET /v1/sub-accounts/{id}/keys`	Seine Schlüssel auflisten, einschließlich widerrufener und abgelaufener
`POST /v1/sub-accounts/{id}/keys`	Einen Schlüssel ausstellen
`DELETE /v1/sub-accounts/{id}/keys/{keyId}`	Einen Schlüssel widerrufen

Erste Schritte

Grundlagen

Antwort-Engines

Suche und Webdaten

Anfrageoptionen

Recherche

GEO-Monitoring

Konto und Daten

Unterkonten: Schlüssel, Limits und Verbrauch pro Endkunde

So funktioniert ein Unterkonto

Wer Unterkonten verwalten kann

Unterkonto und Schlüssel anlegen

Schlüssel verwalten

Limits

Ein Unterkonto jetzt prüfen

Verbrauch und Abrechnung

Alle Unterkonten

Ein Unterkonto

Sperren und entsperren

Fehler

Endpunkte

​So funktioniert ein Unterkonto

​Wer Unterkonten verwalten kann

​Unterkonto und Schlüssel anlegen

​Schlüssel verwalten

​Limits

​Ein Unterkonto jetzt prüfen

​Verbrauch und Abrechnung

​Alle Unterkonten

​Ein Unterkonto

​Sperren und entsperren

​Fehler

​Endpunkte

So funktioniert ein Unterkonto

Wer Unterkonten verwalten kann

Unterkonto und Schlüssel anlegen

Schlüssel verwalten

Limits

Ein Unterkonto jetzt prüfen

Verbrauch und Abrechnung

Alle Unterkonten

Ein Unterkonto

Sperren und entsperren

Fehler

Endpunkte