Balance Query
curl --request GET \
--url https://maas.gravitex.ai/prod-api/api/account/balanceimport requests
url = "https://maas.gravitex.ai/prod-api/api/account/balance"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://maas.gravitex.ai/prod-api/api/account/balance', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://maas.gravitex.ai/prod-api/api/account/balance",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://maas.gravitex.ai/prod-api/api/account/balance"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://maas.gravitex.ai/prod-api/api/account/balance")
.asString();require 'uri'
require 'net/http'
url = URI("https://maas.gravitex.ai/prod-api/api/account/balance")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_bodyInterface module
Balance Query
Query the balance and usage of an account or API key
GET
/
prod-api
/
api
/
account
/
balance
Balance Query
curl --request GET \
--url https://maas.gravitex.ai/prod-api/api/account/balanceimport requests
url = "https://maas.gravitex.ai/prod-api/api/account/balance"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://maas.gravitex.ai/prod-api/api/account/balance', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://maas.gravitex.ai/prod-api/api/account/balance",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://maas.gravitex.ai/prod-api/api/account/balance"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://maas.gravitex.ai/prod-api/api/account/balance")
.asString();require 'uri'
require 'net/http'
url = URI("https://maas.gravitex.ai/prod-api/api/account/balance")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_bodyEndpoint details
| Item | Details |
|---|---|
| Base URL | https://maas.gravitex.ai/prod-api |
| Data format | application/json |
| Character encoding | UTF-8 |
| Protocol | HTTPS (required) |
| Currency | USD (US dollars) |
1. Authentication
Send a Bearer credential in the HTTP header. Use either of the following credentials.| Credential | Where to find it | Query scope |
|---|---|---|
| System access token | Console โ Personal Settings โ System Access Token | Entire account |
| API key | Console โ Token Management. Keys usually start with sk-. | This key only |
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Use Bearer <credential> with either credential above. |
# Option 1. System access token
Authorization: Bearer <access_token>
# Option 2. API key
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
2. Common response structure
{
"code": 200,
"msg": "ๆไฝๆๅ",
"data": { }
}
| Field | Type | Description |
|---|---|---|
code | integer | Application status code. 200 indicates success. |
msg | string | Status message |
data | object | Response data. Returns null on failure. |
Application status codes
| Code | Description |
|---|---|
| 200 | Success |
| 401 | Authentication failed (missing, invalid, or disabled credential) |
Check code in the response body to determine whether the request succeeded.
Amount format
- All amounts are in US dollars (USD) and are returned as strings to avoid loss of floating-point precision.
- Balance amounts always have four decimal places, for example
"986.9275". - Model unit prices have no zero padding, for example
"40","2.5", and"0.00075".
3. Balance query
GET /api/account/balance
data.type to identify it.
3.1 Account balance with a system access token (type = account)
| Field | Type | Description |
|---|---|---|
type | string | Always account |
username | string | Account username |
group | string | Account group |
currency | string | Always USD |
balance | string | Remaining balance |
usedAmount | string | Amount used |
totalAmount | string | Total amount (remaining plus used) |
{
"code": 200,
"msg": "ๆไฝๆๅ",
"data": {
"type": "account",
"username": "demo_user",
"group": "default",
"currency": "USD",
"balance": "986.9275",
"usedAmount": "213.0725",
"totalAmount": "1200.0000"
}
}
An enterprise sub-account can retrieve only its own balance.
3.2 Key quota with an API key (type = token)
| Field | Type | Description |
|---|---|---|
type | string | Always token |
tokenName | string | Key name |
group | string | Key group. An empty value means the key inherits the account group. |
unlimited | boolean | Whether the key has unlimited quota |
currency | string | Always USD |
balance | string | Remaining amount available to the key |
usedAmount | string | Amount used by the key |
totalAmount | string | Total key quota (remaining plus used) |
expiresAt | integer | Expiration timestamp in seconds. 0 indicates no expiration. |
modelLimitsEnabled | boolean | Whether model restrictions are enabled |
modelLimits | string[] | Models the key can call. An empty array is returned when restrictions are disabled. |
{
"code": 200,
"msg": "ๆไฝๆๅ",
"data": {
"type": "token",
"tokenName": "my-key",
"group": "",
"unlimited": false,
"currency": "USD",
"balance": "100.0000",
"usedAmount": "50.0000",
"totalAmount": "150.0000",
"expiresAt": 0,
"modelLimitsEnabled": false,
"modelLimits": []
}
}
A key withunlimited = truehas no key-level quota, sobalancecan be negative. UseusedAmountto track key usage and the account balance to determine available funds.
4. Request examples
# Query the account balance with a system access token
curl -s "https://maas.gravitex.ai/prod-api/api/account/balance" \
-H "Authorization: Bearer <access_token>"
# Query the quota for an API key
curl -s "https://maas.gravitex.ai/prod-api/api/account/balance" \
-H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx"
5. Notes
- Refresh interval. Balance data refreshes within about one minute. Top-ups and charges may take a short time to appear.
- Final charges. Use the endpoint for queries and estimates. Refer to your bill for final charges.
- Credential security. Keep system access tokens private because they provide access to account-wide information. To query one keyโs quota, use that API key.
