Grok passesGrok Quota team
For accounts with a Grok Quota team: create unit-based Grok image and video keys for each member straight from your own system — buy units once, use them over time, they never expire.
Framewharf issues an account with a Grok Quota team a management key starting with fwquota_. Send it in the header Authorization: Bearer. The management key only creates, lists, edits and deletes the team's keys, reads the budget history and reads how many keys can still be created; the member key you get back is the one that calls models, and it starts with sk-.
Each key is sold by units: 504000 per 1000 units. One video — new, edited or extended — is 1 units and one image is 0.25 units, regardless of length or resolution; failed jobs refund their units. Units never expire, and each key runs at most 10 jobs at a time.
The team budget is a prepaid wallet. Creating a key or adding units deducts the price of those units immediately; deleting a key refunds its unused units to the budget. Every budget change is one line in the budget history.
https://framewharf.com/api/v1/grok-quota/keysAuthorization: Bearer fwquota_...Create a new unit key. Both fields are required:
curl "https://framewharf.com/api/v1/grok-quota/keys" \
-H "Authorization: Bearer fwquota_..." \
-H "Content-Type: application/json" \
-d '{ "name": "Customer A", "quota": 5000 }'The key field is returned only once, in this response. Hand it to the member to call the Grok image and video API like any other key. concurrent is how many jobs the key can run at once, price_vnd is the amount just deducted from the budget, free_vnd is the remaining balance.
{
"id": "cm...",
"name": "Customer A",
"key": "sk-...",
"quota": 5000,
"concurrent": 10,
"price_vnd": 2520000,
"free_vnd": 22680000
}https://framewharf.com/api/v1/grok-quota/keysReturns the budget granted (budget_vnd), what the keys have spent after refunds (allocated_vnd), the remaining balance (free_vnd, always budget_vnd − allocated_vnd) and every key of the team, newest first.
{
"budget_vnd": 25200000,
"allocated_vnd": 2520000,
"free_vnd": 22680000,
"keys": [
{
"id": "cm...",
"name": "Customer A",
"quota": 5000,
"units_left": 4987.75,
"key_hint": "sk-...abcd",
"refund_vnd": 2513826,
"created_at": "2026-10-29T08:00:00.000Z",
"last_used_at": "2026-10-29T09:12:00.000Z"
}
]
}quota is the total units bought for the key, units_left is the units remaining (in quarter units when images are involved; null when it couldn't be read), refund_vnd is the amount refunded if the key were deleted at the time of the read.
https://framewharf.com/api/v1/grok-quota/keys/{id}Edit a key in place: the member keeps the key they already use. Send only the fields you want to change:
curl -X PATCH "https://framewharf.com/api/v1/grok-quota/keys/cm..." \
-H "Authorization: Bearer fwquota_..." \
-H "Content-Type: application/json" \
-d '{ "add_quota": 2000 }'{
"id": "cm...",
"name": "Customer A",
"quota": 7000,
"charged_vnd": 1008000,
"free_vnd": 21672000
}charged_vnd is the price of the added units, deducted from the budget immediately, and free_vnd is the balance afterwards. A key that ran out of units works again right after the top-up. Adding units needs enough balance; renaming always works.
https://framewharf.com/api/v1/grok-quota/keys/{id}Delete a member's key. The key stops working immediately. The value of its unused units is settled and refunded to the budget 10 minutes later — once every last request of the key, including videos still rendering, has been billed — as a key_delete line in the budget history. The response is 204.
curl -X DELETE "https://framewharf.com/api/v1/grok-quota/keys/cm..." \
-H "Authorization: Bearer fwquota_..."https://framewharf.com/api/v1/quotaAuthorization: Bearer sk-...Members check their remaining units with their own sk- key — no management key needed:
curl "https://framewharf.com/api/v1/quota" \
-H "Authorization: Bearer sk-..."{
"object": "quota",
"total": 7000,
"used": 12.25,
"remaining": 6987.75,
"video_units": 1,
"image_units": 0.25
}used and remaining are in units, so they can be fractional in quarters when images are involved. Once units run out, every request from the key is rejected until you add more.
https://framewharf.com/api/v1/grok-quota/usageReturns the videos, images, units used and money spent per key and for the whole team, by hour or by day in Vietnam time — the figures you reconcile and bill your own customers with. Every parameter is optional:
curl "https://framewharf.com/api/v1/grok-quota/usage?bucket=hour&start=2026-10-29T00:00:00%2B07:00&end=2026-10-30T00:00:00%2B07:00" \
-H "Authorization: Bearer fwquota_..."{
"bucket": "hour",
"start": "2026-10-28T17:00:00.000Z",
"end": "2026-10-29T17:00:00.000Z",
"totals": { "videos": 12, "images": 1, "failed": 1, "units_used": 12.25, "spend_vnd": 6174, "refunded_vnd": 504 },
"slots": [
{ "slot": "2026-10-29 09", "videos": 8, "images": 0, "failed": 1, "units_used": 8, "spend_vnd": 4032, "refunded_vnd": 504 },
{ "slot": "2026-10-29 10", "videos": 4, "images": 1, "failed": 0, "units_used": 4.25, "spend_vnd": 2142, "refunded_vnd": 0 }
],
"keys": [
{
"id": "cm...",
"name": "Customer A",
"deleted_at": null,
"totals": { "videos": 12, "images": 1, "failed": 1, "units_used": 12.25, "spend_vnd": 6174, "refunded_vnd": 504 },
"slots": [
{ "slot": "2026-10-29 09", "videos": 8, "images": 0, "failed": 1, "units_used": 8, "spend_vnd": 4032, "refunded_vnd": 504 },
{ "slot": "2026-10-29 10", "videos": 4, "images": 1, "failed": 0, "units_used": 4.25, "spend_vnd": 2142, "refunded_vnd": 0 }
]
}
]
}slot is YYYY-MM-DD by day or YYYY-MM-DD HH by hour, Vietnam time; empty slots are omitted. spend_vnd is the money spent, net of refunds for failed jobs; refunded_vnd is that refund; failed is the number of failed jobs whose units were refunded; units_used is spend_vnd divided by the price of one unit, which can be fractional in quarters when images are involved. Detailed figures are kept for the last 8 days, so read them periodically and store them on your side; each key's lifetime total is quota minus units_left under View budget and keys. Deleted keys stay in the report, with deleted_at set to when they were deleted.
https://framewharf.com/api/v1/grok-quota/transactionsReturns the budget lines, newest first: each grant, key creation, unit top-up or deletion refund is one line, with the balance right after it.
curl "https://framewharf.com/api/v1/grok-quota/transactions?limit=50" \
-H "Authorization: Bearer fwquota_..."{
"transactions": [
{
"id": "cm...",
"type": "key_update",
"source": "api",
"amount_vnd": -1008000,
"balance_after_vnd": 21672000,
"key_id": "cm...",
"key_name": "Customer A",
"description": "Nạp thêm 2.000 lượt cho key Customer A",
"created_at": "2026-10-29T10:00:00.000Z"
},
{
"id": "cm...",
"type": "key_create",
"source": "api",
"amount_vnd": -2520000,
"balance_after_vnd": 22680000,
"key_id": "cm...",
"key_name": "Customer A",
"description": "Tạo key Customer A: 5.000 lượt",
"created_at": "2026-10-29T08:00:00.000Z"
}
],
"next_cursor": null
}A positive amount_vnd adds to the balance, a negative one deducts. source is admin when Framewharf made the change, console or api when you did. Line types:
https://framewharf.com/api/v1/grok-quota/capacityEvery quota key runs key_concurrent jobs at once and takes that many of the parallel requests still on sale right now. This endpoint tells how many new keys can still be created; once none are left, creating a key gets a 409. Topping up an existing key needs no room.
curl "https://framewharf.com/api/v1/grok-quota/capacity" \
-H "Authorization: Bearer fwquota_..."{
"open": true,
"available": 1500,
"key_concurrent": 10,
"available_keys": 150
}available is the parallel requests still on sale, available_keys the new keys that can still be created (available divided by key_concurrent, rounded down), and open is false when no further key fits. The figure refreshes every 15 seconds, while creating a key always checks again at that moment. The units on sale are a separate limit: reaching it gets creating and topping up a 409 as well.
Every error has the shape { "error": { "message": string } }.