> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 接入用量

> 读取每个来源接入了多少数据，以及单个来源按小时的趋势。

```http theme={null}
GET /api/v1/streams/usage
```

返回每个来源在一段时间内接入了多少数据，以及预算用到了哪里。需要 `intake_usage.read`；在 `_sys` 组织中也可以用 `sys.telemetry.read`。

未知的数值是 `null`，不是 0。读不出记录时，`available` 为 `false`，所有数值都是 `null`。计量在这段时间内才开始时，`complete` 为 `false`，数值是下限。

**查询参数**

| 参数 | 默认值 | 说明 |
| - | - | - |
| `dimension` | `credential` | `credential`、`stream` 或 `service`。 |
| `window_secs` | 86400 | 时间窗口长度，范围 3600 到 2678400。窗口从整点开始。 |

`source_key` 的形式：凭证是 `<credential_kind>:<id>`（`api_token`、`connector`、`user`、`internal`），数据流是 `<stream_type>:<name>`，服务是服务名；没有标注服务的事件是空字符串，超出上限的服务是 `*`。

```bash cURL theme={null}
curl "http://localhost:5080/api/v1/streams/usage?dimension=credential&window_secs=86400" \
  -H "authorization: Bearer $MS_TOKEN"
```

```json 200 theme={null}
{
  "generated_at_micros": 1790000000000000,
  "window_start_micros": 1789912800000000,
  "window_end_micros": 1790000000000000,
  "window_secs": 86400,
  "dimension": "credential",
  "available": true,
  "metering_started_at_micros": 1785000000000000,
  "total_bytes": 21474836480,
  "total_events": 15000000,
  "truncated": false,
  "sources": [
    {
      "source_key": "api_token:3KE0ot1NtfCTJ3V3XxBNbqx9Y62",
      "label": {
        "kind": "api_token",
        "subkind": "personal",
        "name": "checkout-prod",
        "detail": "ms_1a2b3c4d5e6f7a8b",
        "missing": false
      },
      "budgetable": true,
      "intake_bytes": 21474836480,
      "events": 15000000,
      "complete": true,
      "share": 1.0,
      "budget": {
        "id": "3KE0p2QvLdXw9mB7sYcT1uZaH4n",
        "dimension": "credential",
        "source_key": "api_token:3KE0ot1NtfCTJ3V3XxBNbqx9Y62",
        "period": "day",
        "limit_size": 10240,
        "warn_percent": 80,
        "notify_user_ids": ["3KE0mZ8rHq2Nf6Vt4Kd1XbLwP7s"],
        "updated_at_micros": 1789900000000000,
        "period_start_micros": 1789948800000000,
        "used_bytes": 21474836480,
        "used_complete": true,
        "used_ratio": 2.0,
        "state": "exceeded"
      }
    }
  ]
}
```

## 单个来源

```http theme={null}
GET /api/v1/streams/usage/detail
```

返回单个来源在这段时间内的合计、按桶聚合的小时数据，以及它在另外两个维度上的拆分，每个维度最多 20 个来源。

| 参数 | 默认值 | 说明 |
| - | - | - |
| `dimension` | 必填 | `credential`、`stream` 或 `service`。 |
| `source_key` | 必填 | 来源，取值同 `GET /api/v1/streams/usage` 返回的。 |
| `window_secs` | 86400 | 范围 3600 到 2678400。 |
| `bucket_count` | 24 | 桶数，范围 6 到 48。 |


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