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

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

> 顧客ごとにAPIキー、クレジット上限、同時実行上限を分け、結果を分離し、顧客ごとの使用量を取得します。請求書はひとつです。

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`になります。制限付きのキーが、自身の制限のないキーを発行できてしまうのを防ぐためです。サブアカウント自身のキーも同じエラーになります。

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

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

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

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

| フィールド | 必須 | 説明 |
| - | - | - |
| `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`を返します。上限名の書き間違いで顧客が無制限のまま残ることはありません。

次にサブアカウントのキーを発行します。

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

キーにはダッシュボードのキーと同じ任意の設定を指定できます: `name`(1〜64文字、既定値`default`)、`allowedTaskTypes`、`dailyCreditLimit`、`expiresAt`(5分後〜2年後)。制限のないキーにはボディを送らないでください。

サブアカウントが持てる有効なキーは最大5個です。失効済み・期限切れのキーは数えません。6個目は`409 KEY_LIMIT`を返すので、先にどれかを失効させてください。

顧客のキーは他のキーと同じく、すべてのエンドポイントで使えます。

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

## キーを管理する

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

```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}`はキーを失効させ、`{"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` |

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

```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`は、月間の集計がリセットされる次のUTC月の初日までの秒数です。アカウント全体の上限は[クレジットと制限](/ja/concepts/credits-and-limits.md)を参照してください。

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

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

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

上の値は例です。`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日です。

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

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

例:

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

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

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

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

例:

```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`と`tasks`は`days`の合計です。
* `days`は請求のあったUTC日付とエンジンごとに1行で、日付順、次に`taskType`順です。請求のない日の行はありません。
* `taskType: "OTHER"`はタスク以外の請求で、たとえばモニターの[競合分析](/ja/monitors.md#コストとスケジュール)です。クレジットは加算されますが、`tasks`は加算されません。

## 停止と再開

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

* そのキーは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`](/ja/api-reference/sub-accounts/create-sub-account) | 作成 |
| [`GET /v1/sub-accounts`](/ja/api-reference/sub-accounts/list-sub-accounts) | 一覧。`externalId`、`limit`、`cursor`を指定可能 |
| [`GET /v1/sub-accounts/{id}`](/ja/api-reference/sub-accounts/get-sub-account) | サブアカウントひとつ。`activeTasks`付き |
| [`PATCH /v1/sub-accounts/{id}`](/ja/api-reference/sub-accounts/update-sub-account) | 設定の変更、停止、再開 |
| [`GET /v1/sub-accounts/usage`](/ja/api-reference/sub-accounts/list-usage) | サブアカウントごとの合計 |
| [`GET /v1/sub-accounts/{id}/usage`](/ja/api-reference/sub-accounts/get-usage) | ひとつのサブアカウントの日別・エンジン別使用量 |
| [`GET /v1/sub-accounts/{id}/keys`](/ja/api-reference/sub-accounts/list-keys) | 失効済み・期限切れを含むキーの一覧 |
| [`POST /v1/sub-accounts/{id}/keys`](/ja/api-reference/sub-accounts/issue-key) | キーの発行 |
| [`DELETE /v1/sub-accounts/{id}/keys/{keyId}`](/ja/api-reference/sub-accounts/revoke-key) | キーの失効 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.