> ## Documentation Index
> Fetch the complete documentation index at: https://docs.madiad.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Mức sử dụng
> Đọc hạn mức của gói và phần bạn đã dùng trong chu kỳ hiện tại.
`GET /v1/usage` trả về toàn bộ hạn mức tài khoản của bạn cùng phần đã dùng trong chu kỳ thanh toán hiện tại: gói, mốc thời gian chu kỳ và một bộ đếm cho từng loại tài nguyên. Dùng nó để hiển thị widget mức sử dụng, quyết định có gửi job FFmpeg hay không, hoặc kiểm tra còn bao nhiêu slot Profile trước khi tạo connect link.
Đăng bài không giới hạn trên mọi gói trả phí (xem [Bài đăng](/vi/concepts/posts)), nên `uploads.limit` luôn là `null`, bộ đếm `used` vẫn chạy như một số liệu ghi nhận, không phải hạn mức.
## Request
```bash theme={null}
curl https://api.madiad.com/v1/usage \
-H "Authorization: Bearer $MADIAD_API_KEY"
```
Endpoint này chỉ hoạt động trong phạm vi tài khoản sở hữu API key: không nhận tham số nào và không bao giờ trả về số liệu của tài khoản khác. Đây là request `GET`, không tiêu tốn phút FFmpeg hay lượt đăng nào, chỉ tính vào [rate limit](/vi/concepts/rate-limits) mỗi phút.
## Response
```json theme={null}
{
"plan": { "id": "growth", "name": "Growth", "price_vnd_monthly": 390000 },
"status": "active",
"period": { "start": "2026-07-07", "renews_on": "2026-08-07", "expires_on": null },
"uploads": { "used": 180, "limit": null, "remaining": null },
"ffmpeg_minutes": { "used": 12, "limit": 150, "remaining": 138 },
"profiles": { "used": 4, "limit": 4, "remaining": 0 },
"direct_messages": {
"used": 0,
"limit": 0,
"remaining": 0,
"day": "2026-07-20",
"included": false
},
"api_keys": { "used": 2, "limit": null, "remaining": null },
"features": { "schedule": true, "queue": true, "analytics": true, "webhooks": true }
}
```
### Bộ đếm
Mọi tài nguyên có hạn mức đều dùng chung ba field:
| Field | Ý nghĩa |
| ----------- | -------------------------------------------------------------------------------------------------- |
| `used` | Đã dùng trong chu kỳ hiện tại (riêng `direct_messages` là đã dùng trong ngày hôm nay). |
| `limit` | Hạn mức. **`null` nghĩa là không giới hạn.** `0` nghĩa là gói của bạn không bao gồm tài nguyên đó. |
| `remaining` | `limit - used`, không xuống dưới 0. **Là `null` khi `limit` là `null`.** |
Hãy hiểu `limit: null` là không giới hạn, không phải 0: fallback `remaining ?? 0` sẽ hiển thị sai với người dùng của bạn rằng họ đã hết hạn mức.
### Các field
| Field | Ý nghĩa |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `plan` | Id, tên hiển thị và giá theo tháng (VND) của gói đang hoạt động (`null` với gói Custom). |
| `status` | Trạng thái tài khoản. Ở response này luôn là `active`: tài khoản `expired` hoặc `banned` bị trả `403` trước khi endpoint chạy (xem phần lỗi bên dưới). |
| `period.start` | Ngày đầu tiên của chu kỳ hiện tại, dạng `YYYY-MM-DD`. |
| `period.renews_on` | Ngày chu kỳ chuyển sang kỳ mới và các bộ đếm được reset. |
| `period.expires_on` | Ngày kết thúc thời hạn đã thanh toán nếu có, ngược lại là `null`. |
| `uploads` | Số bài đã đăng trong chu kỳ. `limit` là `null` trên mọi gói trả phí. |
| `ffmpeg_minutes` | Số phút [FFmpeg](/vi/concepts/ffmpeg) trong chu kỳ. Hạn mức tính cho cả tài khoản: mọi thương hiệu dùng chung hạn mức này. |
| `profiles` | Số [Profiles](/vi/concepts/profiles) đã kết nối so với giới hạn của gói. |
| `direct_messages` | Số DM hôm nay. `included: false` nghĩa là gói của bạn không có [tính năng tương tác](/vi/concepts/engagement). |
| `api_keys` | Số key đang hoạt động (chưa thu hồi). |
| `features` | Các cờ tính năng của gói đang hoạt động. |
## Mốc thời gian chu kỳ
Chu kỳ của bạn được neo theo ngày kích hoạt gói, tính theo giờ Việt Nam (UTC+7), **không phải** ngày mùng 1 của tháng dương lịch. Gói kích hoạt ngày 7 sẽ reset vào ngày 7 hằng tháng. Nếu ngày neo không tồn tại trong tháng ngắn hơn, hệ thống lùi về ngày cuối cùng của tháng đó.
`period.start` và `period.renews_on` luôn báo đúng ngày thực tế, nên hãy đọc hai field này thay vì tự tính mốc đầu/cuối tháng.
## Kiểm tra trước khi thao tác
```bash theme={null}
# Chỉ gửi job FFmpeg nếu còn phút (null = không giới hạn).
REMAINING=$(curl -s https://api.madiad.com/v1/usage \
-H "Authorization: Bearer $MADIAD_API_KEY" | jq '.ffmpeg_minutes.remaining')
if [ "$REMAINING" = "null" ] || [ "$REMAINING" -gt 0 ]; then
echo "Có thể gửi job"
fi
```
## Lỗi
| Status | Code | Ý nghĩa |
| ------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `401` | `unauthorized` | API key thiếu hoặc không hợp lệ. |
| `403` | `forbidden` | Tài khoản đang ở trạng thái `expired` hoặc `banned`. Tài khoản hết hạn sẽ đăng bài lại ngay khi khoản gia hạn được ghi nhận. |
| `429` | `rate_limited` | Vượt giới hạn số request mỗi phút. |
Xem [Lỗi](/vi/concepts/errors) để biết danh sách đầy đủ.