وضعیت بودجه با GET /v1/budget/me
این مسیر به کلاینت میگوید با همان کلید یا توکنی که درخواست میفرستد، از هر سقف بودجه چقدر باقی مانده است. با آن میتوانید پیش از ارسال درخواستهای سنگین، یا بعد از دریافت خطای budget_exceeded، وضعیت را به کاربر نشان دهید.
هر کلید یا توکن درگاه که بتواند درخواست مدل بفرستد، میتواند این مسیر را بخواند. پاسخ ذخیره نمیشود (Cache-Control: no-store).
درخواست
curl https://api.godarai.ir/v1/budget/me \
-H "Authorization: Bearer $GODARAI_API_KEY"
پاسخ
{
"object": "budget_status",
"unit": "credit",
"rules": [
{
"rule_id": "support-daily-budget",
"name": "بودجه روزانه پشتیبانی",
"scope": "team",
"limit": "250.00",
"spent": "112.40",
"remaining": "137.60",
"window_end": "2026-10-18T00:00:00Z",
"on_exceed": "block"
}
],
"tenant_balance": {
"remaining": "1830.25",
"reserved": "4.10",
"window_end": "2026-11-01T00:00:00Z"
}
}
| فیلد | معنی |
|---|---|
unit | همیشه credit. همه مقدارها رشتههای کردیت با دو رقم اعشارند. |
rules[].scope | نوع تفکیک قانون؛ مثل tenant، user، team یا virtualaccount. |
rules[].spent | کردیت مصرفشده در پنجره فعلی همان قانون. |
rules[].remaining | سقف منهای مصرف قطعی و رزروهای در جریان. |
rules[].window_end | زمان شروع پنجره بعدی قانون. |
rules[].on_exceed | block اگر پر شدن سقف درخواست را رد کند، alert اگر فقط ثبت شود. |
tenant_balance | کردیتی که فضای کاری در ماه جاری هنوز میتواند خرج کند. فقط برای فراخوانندهای که دسترسی خواندن صورتحساب (billing:read یا billing:manage) یا نقش مدیر دارد برگردانده میشود. |
چه قوانینی فهرست میشوند؟
- فقط قوانین فعالی که به هویت فراخواننده میخورند؛ یعنی کل فضای کاری، کاربر، تیم یا اکانت مجازی.
- قوانینی که «بهازای هر مدل» یا «بهازای فراداده» تفکیک میشوند فهرست نمیشوند، چون برای هر مقدار پنجره جدا دارند.
- شرطهای وابسته به خود درخواست، مثل مدل یا فراداده، بدون درخواست قابل ارزیابی نیستند. قانونی که به هویت فراخواننده بخورد، صرفنظر از این شرطها فهرست میشود.
خطاها
| وضعیت | کد | توضیح |
|---|---|---|
401 | unauthorized | کلید یا توکن معتبر نیست. |
503 | billing_unavailable | وضعیت بودجه موقتا قابل خواندن نیست؛ کمی بعد دوباره تلاش کنید. |