> ## 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` 在你的上限之内
  限制它排队和运行中的任务数。两者都是可选的。
* **只有一层。** 子账户不能再拥有子账户。其监测器的提醒邮件发送给你账户的管理员。

## 谁可以管理子账户

请使用你自己的、没有引擎范围限制和每日积分上限的 API 密钥调用 `/v1/sub-accounts` 接口。其他密钥会收到
`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 积分，最多两位小数。省略或传 `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 个有效密钥；已吊销和已过期的密钥不计入。签发第六个会返回 `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 月开始的秒数，届时月度统计重新开始。账户级上限见
[积分与限制](/zh/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` 是仍在运行的
任务所预留的积分。

## 用量与计费

每一笔扣费也会出现在你自己的账单明细中；以下接口按客户拆分这些扣费。失败的任务从不扣费，也不计入统计。
积分金额最多两位小数。

* `GET /v1/sub-accounts` 按创建时间从早到晚列出子账户，每项附带本月 `usage`。用 `limit`（默认 100，最多 1,000）
  分页，并把 `nextCursor` 作为 `cursor` 传回。
* `GET /v1/sub-accounts/usage` 返回一个 UTC 日期范围内每个子账户的合计。
* `GET /v1/sub-accounts/{id}/usage` 返回单个子账户按天和引擎的扣费。

两个用量接口都接受 `YYYY-MM-DD` 格式的 `from` 和 `to`（含首尾）。`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 日期和引擎各占一行，先按日期、再按 `taskType` 排序。没有扣费的日期不会出现。
* `taskType: "OTHER"` 是不属于任务的扣费，例如监测器的[竞品读取](/zh/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"}'
```

* 它的密钥会在五秒内开始返回 `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`](/zh/api-reference/sub-accounts/create-sub-account) | 创建 |
| [`GET /v1/sub-accounts`](/zh/api-reference/sub-accounts/list-sub-accounts) | 列表，支持 `externalId`、`limit` 和 `cursor` |
| [`GET /v1/sub-accounts/{id}`](/zh/api-reference/sub-accounts/get-sub-account) | 单个子账户，包含 `activeTasks` |
| [`PATCH /v1/sub-accounts/{id}`](/zh/api-reference/sub-accounts/update-sub-account) | 修改设置、暂停或恢复 |
| [`GET /v1/sub-accounts/usage`](/zh/api-reference/sub-accounts/list-usage) | 每个子账户的合计 |
| [`GET /v1/sub-accounts/{id}/usage`](/zh/api-reference/sub-accounts/get-usage) | 单个子账户按天和引擎的用量 |
| [`GET /v1/sub-accounts/{id}/keys`](/zh/api-reference/sub-accounts/list-keys) | 列出密钥，包括已吊销和已过期的密钥 |
| [`POST /v1/sub-accounts/{id}/keys`](/zh/api-reference/sub-accounts/issue-key) | 签发密钥 |
| [`DELETE /v1/sub-accounts/{id}/keys/{keyId}`](/zh/api-reference/sub-accounts/revoke-key) | 吊销密钥 |


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