# 消息用量 (GET)

获取你当前套餐的[每日上限](https://info.pocketalert.app/features/daily-limits.md)下今日的消息用量。

## 端点

```
GET https://api.pocketalert.app/v1/messages/usage
```

## 身份验证

> **Info: 必填**
>
> 在请求中包含以下任一请求头：
> - `Token: <your-api-key>` — 从 [API 密钥](https://pocketalert.app/account/apikeys)获取
> - `Authorization: Bearer <jwt-token>` — 来自[登录](https://info.pocketalert.app/api/user/login.md)

## 请求

### 请求示例

**cURL**

```bash
curl -X GET "https://api.pocketalert.app/v1/messages/usage" \
  -H "Token: your-api-key"
```

**JavaScript**

```javascript
const response = await fetch('https://api.pocketalert.app/v1/messages/usage', {
  headers: { 'Token': 'your-api-key' }
});
const usage = await response.json();
```

**Python**

```python
import requests

response = requests.get(
    'https://api.pocketalert.app/v1/messages/usage',
    headers={'Token': 'your-api-key'}
)
print(response.json())
```

**PHP**

```php
$response = Http::withHeaders([
    'Token' => 'your-api-key',
])->get('https://api.pocketalert.app/v1/messages/usage');

return $response->json();
```

## 响应

### 成功响应

> **Tip: 200 OK**
>
> 返回今日的用量。日期以 UTC 时间为准。

| 字段 | 类型 | 说明 |
|-------|------|-------------|
| `used` | integer | 今日已接收的消息数 |
| `limit` | integer \| null | 每日允许的消息数，不限量套餐为 `null` |
| `unlimited` | boolean | 当套餐没有每日上限时为 `true` |
| `rejected` | integer | 今日因达到上限而被拒绝的请求数 |
| `resets_at` | string | 下次重置时间，UTC 时间 00:00，RFC3339 格式 |

```json
{
  "used": 42,
  "limit": 50,
  "unlimited": false,
  "rejected": 0,
  "resets_at": "2026-09-22T00:00:00Z"
}
```

不限量套餐的响应：

```json
{
  "used": 1280,
  "limit": null,
  "unlimited": true,
  "rejected": 0,
  "resets_at": "2026-09-22T00:00:00Z"
}
```

### 错误响应

| 状态码 | 说明 |
|:------:|-------------|
| `401` | 未授权 — 令牌无效或缺失 |

> **Tip: 使用场景**
>
> 在发送大量告警之前，先将 `used` 与 `limit` 进行比较；也可以在你自己的控制台中显示剩余配额。每次[创建消息](https://info.pocketalert.app/api/messages/create.md)的响应中都会以 `X-PA-Daily-*` 请求头返回相同的数据。
