サブアカウント: エンドカスタマーごとのキー、上限、使用量

querying.aiを自社製品の中で使う場合は、顧客ごとにサブアカウントをひとつ作成します。サブアカウントは独自のAPIキー、上限、タスク、バッチ、モニターを持ちます。クレジットはあなたの残高から引かれ、使用量エンドポイントで各顧客にいくら請求するかがわかります。

サブアカウントの動作

独自のキーと結果。 サブアカウントのキーは他のキーと同じようにタスク、バッチ、モニターを送信・取得し、自分の作業だけを見ます。AcmeのキーでつくったタスクはGlobexのキーとあなたのキーには404を返します。
あなたのクレジット。 タスクの料金はあなたの残高から引かれます。サブアカウントに残高はないため、サブアカウントのキーでGET /v1/creditsやGET /v1/usageを呼ぶと403 SUB_ACCOUNT_FORBIDDENが返ります。
あなたの処理能力。 プランまたは契約の同時実行上限は、あなたのタスクとすべてのサブアカウントのタスクの合計に適用されます。サブアカウントを作っても処理能力は増えません。GET /v1/async/statusはこの共有キューをあなたのキーでまとめて返し、サブアカウントのキーで呼ぶと403 SUB_ACCOUNT_FORBIDDENが返ります。
あなたのモニター上限。 GET /v1/monitors/capabilitiesのmonitors上限は、あなたのモニターとすべてのサブアカウントのモニターを合わせて数えます。promptsとtasksPerRunの上限も、サブアカウントのモニターにあなたのモニターと同じく適用されます。
独自の上限。 monthlyCreditLimitはUTCの暦月に請求できるクレジットの上限です。concurrencyLimitはあなたの上限の内側で、待機中と実行中のタスク数を制限します。どちらも任意です。
1階層のみ。 サブアカウントはサブアカウントを持てません。そのモニターのアラートメールはあなたのアカウントの管理者に届きます。

サブアカウントを管理できるキー

/v1/sub-accountsエンドポイントは、エンジンの範囲指定と日次クレジット上限のない、あなた自身のAPIキーで呼び出します。それ以外のキーは403 SUB_ACCOUNT_FORBIDDENになります。制限付きのキーが、自身の制限のないキーを発行できてしまうのを防ぐためです。サブアカウント自身のキーも同じエラーになります。

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

サブアカウントとキーを作成する

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

レスポンスは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 }
  }
}

フィールド	必須	説明
`name`	はい	1〜128文字。
`externalId`	いいえ	この顧客を表すあなた側のid。1〜128文字で、あなたのサブアカウントの中で一意です。同じ値で再度作成すると`409 SUB_ACCOUNT_EXISTS`を返すので、再試行しても重複しません。既存のものは`GET /v1/sub-accounts?externalId=cust_acme`で探せます。
`monthlyCreditLimit`	いいえ	0.01〜20,000,000クレジット(小数点以下2桁まで)。省略するか`null`を送ると上限なしです。
`concurrencyLimit`	いいえ	1〜100,000の整数。省略するか`null`を送ると上限なしです。

それ以外のフィールドは400 VALIDATION_ERRORを返します。上限名の書き間違いで顧客が無制限のまま残ることはありません。次にサブアカウントのキーを発行します。

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はこのレスポンスにしか表示されません。今すぐ保存してください。二度と表示されません。

キーにはダッシュボードのキーと同じ任意の設定を指定できます: name(1〜64文字、既定値default)、allowedTaskTypes、dailyCreditLimit、expiresAt(5分後〜2年後)。制限のないキーにはボディを送らないでください。サブアカウントが持てる有効なキーは最大5個です。失効済み・期限切れのキーは数えません。6個目は409 KEY_LIMITを返すので、先にどれかを失効させてください。顧客のキーは他のキーと同じく、すべてのエンドポイントで使えます。

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

キーを管理する

GET /v1/sub-accounts/{id}/keysは、失効済み・期限切れも含め、サブアカウントがこれまで持ったすべてのキーを新しい順に返します。有効なキーはrevokedAtとexpiresAtで判断してください。

{
  "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}はキーを失効させ、{"success": true, "data": {"revoked": "<keyId>"}}を返します。すでに失効しているキーや、そのサブアカウントのものでないキーは404 NOT_FOUNDを返します。

上限

上限	数える対象	達したとき
`monthlyCreditLimit`	今月(UTC)そのサブアカウントに請求されたクレジットと、実行中のタスクが確保しているクレジット	`429 SUB_ACCOUNT_CREDIT_LIMIT`
`concurrencyLimit`	そのサブアカウントの待機中と実行中のタスク	`429 PLAN_CONCURRENCY_LIMIT`, `details.source: "sub_account"`
あなたのプランまたは契約の上限	あなたとすべてのサブアカウントのタスク	`429 PLAN_CONCURRENCY_LIMIT`, `details.source: "plan"` または `"contract"`
あなたの残高	全員	`402 INSUFFICIENT_CREDITS`

自分の上限に達したサブアカウントだけが拒否され、ほかの顧客は処理が続きます。上限を引き上げると次のリクエストから反映されます。

{
  "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は、月間の集計がリセットされる次のUTC月の初日までの秒数です。アカウント全体の上限はクレジットと制限を参照してください。

サブアカウントの現状を確認する

GET /v1/sub-accounts/{id}は、今月の使用量とactiveTasks(いま待機中または実行中のタスク数)付きでサブアカウントを返します。concurrencyLimitと比べると、顧客が上限にどれだけ近いかがわかります。

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

上の値は例です。usageのcreditsとtasksは今月(UTC)請求された分、reservedCreditsは実行中のタスクが確保している分です。

使用量と請求

すべての請求はあなたの請求台帳にもそのまま載ります。以下のエンドポイントはそれを顧客ごとに分けます。失敗したタスクは請求されず、集計にも入りません。クレジット額は小数点以下2桁までです。

GET /v1/sub-accountsはサブアカウントを古い順に返し、それぞれに今月のusageを付けます。limit(既定100、最大1,000)でページを分け、nextCursorをcursorとして送ると次のページです。
GET /v1/sub-accounts/usageは、UTC日付の範囲でサブアカウントごとの合計を返します。
GET /v1/sub-accounts/{id}/usageは、ひとつのサブアカウントの日別・エンジン別の請求を返します。

どちらの使用量エンドポイントもfromとtoをYYYY-MM-DDで受け取り、両端を含みます。fromの既定は今月(UTC)1日、toは今日で、範囲は最大366日です。

すべてのサブアカウント

curl "https://api.querying.ai/v1/sub-accounts/usage?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

例:

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

サブアカウントは多い順に並びます。範囲内に請求のないサブアカウントは含まれません。

ひとつのサブアカウント

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"

例:

{
  "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とtasksはdaysの合計です。
daysは請求のあったUTC日付とエンジンごとに1行で、日付順、次にtaskType順です。請求のない日の行はありません。
taskType: "OTHER"はタスク以外の請求で、たとえばモニターの競合分析です。クレジットは加算されますが、tasksは加算されません。

停止と再開

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

そのキーは5秒以内に401を返すようになります。
モニターの実行が止まり、まだ始まっていないバッチ項目はAPI_KEY_INACTIVEで終わります。
すでに待機中または実行中のタスクは最後まで処理され、請求されます。

{"status": "active"}でキーとモニターが戻ります。各モニターは逃した実行をまとめて行わず、戻ったときに一度だけ実行します。同じPATCHでname、externalId、monthlyCreditLimit、concurrencyLimitも変更でき、nullは上限またはexternalIdを外します。サブアカウントは削除できないため、代わりに停止してください。

エラー

ステータス	コード	原因
`400`	`VALIDATION_ERROR`	JSONが不正、未知のフィールド、範囲外の値、または使用量の範囲が不正です。
`403`	`SUB_ACCOUNT_FORBIDDEN`	キーにエンジンの範囲指定か日次クレジット上限があるか、サブアカウントのキーです。
`404`	`NOT_FOUND`	そのidのサブアカウントがあなたのサブアカウントにないか、そのidの有効なキーがありません。
`409`	`SUB_ACCOUNT_EXISTS`	別のサブアカウントがすでにその`externalId`を持っています。
`409`	`KEY_LIMIT`	サブアカウントにすでに有効なキーが5個あります。

エンドポイント

メソッドとパス	用途
`POST /v1/sub-accounts`	作成
`GET /v1/sub-accounts`	一覧。`externalId`、`limit`、`cursor`を指定可能
`GET /v1/sub-accounts/{id}`	サブアカウントひとつ。`activeTasks`付き
`PATCH /v1/sub-accounts/{id}`	設定の変更、停止、再開
`GET /v1/sub-accounts/usage`	サブアカウントごとの合計
`GET /v1/sub-accounts/{id}/usage`	ひとつのサブアカウントの日別・エンジン別使用量
`GET /v1/sub-accounts/{id}/keys`	失効済み・期限切れを含むキーの一覧
`POST /v1/sub-accounts/{id}/keys`	キーの発行
`DELETE /v1/sub-accounts/{id}/keys/{keyId}`	キーの失効

はじめに

基本概念

回答エンジン

検索とウェブデータ

リクエストオプション

リサーチ

GEOモニタリング

アカウントとデータ

サブアカウント: エンドカスタマーごとのキー、上限、使用量

サブアカウントの動作

サブアカウントを管理できるキー

サブアカウントとキーを作成する

キーを管理する

上限

サブアカウントの現状を確認する

使用量と請求

すべてのサブアカウント

ひとつのサブアカウント

停止と再開

エラー

エンドポイント

​サブアカウントの動作

​サブアカウントを管理できるキー

​サブアカウントとキーを作成する

​キーを管理する

​上限

​サブアカウントの現状を確認する

​使用量と請求

​すべてのサブアカウント

​ひとつのサブアカウント

​停止と再開

​エラー

​エンドポイント

サブアカウントの動作

サブアカウントを管理できるキー

サブアカウントとキーを作成する

キーを管理する

上限

サブアカウントの現状を確認する

使用量と請求

すべてのサブアカウント

ひとつのサブアカウント

停止と再開

エラー

エンドポイント