curl https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/balance \
-H "Authorization: Bearer $MACROSCOPE_API_KEY"
import os, requests
r = requests.get(
"https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/balance",
headers={"Authorization": f"Bearer {os.environ['MACROSCOPE_API_KEY']}"},
)
print(r.json())
const res = await fetch(
"https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/balance",
{ headers: { Authorization: `Bearer ${process.env.MACROSCOPE_API_KEY}` } }
);
console.log(await res.json());
{
"balance": {
"periodStart": "2026-09-01T00:00:00Z",
"periodEnd": "2026-10-01T00:00:00Z",
"balanceAvailable": true,
"availableBalance": {
"amount": "120.50",
"currency": "USD"
},
"ledgerBalance": {
"amount": "500.00",
"currency": "USD"
},
"usageAmount": {
"amount": "379.50",
"currency": "USD"
},
"overageAmount": {
"amount": "0.00",
"currency": "USD"
},
"nextInvoiceAmountDue": {
"amount": "0.00",
"currency": "USD"
},
"seatAmount": {
"amount": "0.00",
"currency": "USD"
},
"agentCreditGranted": {
"amount": "10.00",
"currency": "USD"
},
"agentCreditUsed": {
"amount": "4.20",
"currency": "USD"
},
"agentCreditBalance": {
"amount": "5.80",
"currency": "USD"
},
"amountStatus": "BILLING_AMOUNT_STATUS_PROVISIONAL"
},
"readTime": "2026-09-15T18:00:00Z"
}
{ "code": 16, "message": "unauthenticated" }
API
Get billing balance
Credit balance, usage, and amounts due for the current billing period.
curl https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/balance \
-H "Authorization: Bearer $MACROSCOPE_API_KEY"
import os, requests
r = requests.get(
"https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/balance",
headers={"Authorization": f"Bearer {os.environ['MACROSCOPE_API_KEY']}"},
)
print(r.json())
const res = await fetch(
"https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/balance",
{ headers: { Authorization: `Bearer ${process.env.MACROSCOPE_API_KEY}` } }
);
console.log(await res.json());
{
"balance": {
"periodStart": "2026-09-01T00:00:00Z",
"periodEnd": "2026-10-01T00:00:00Z",
"balanceAvailable": true,
"availableBalance": {
"amount": "120.50",
"currency": "USD"
},
"ledgerBalance": {
"amount": "500.00",
"currency": "USD"
},
"usageAmount": {
"amount": "379.50",
"currency": "USD"
},
"overageAmount": {
"amount": "0.00",
"currency": "USD"
},
"nextInvoiceAmountDue": {
"amount": "0.00",
"currency": "USD"
},
"seatAmount": {
"amount": "0.00",
"currency": "USD"
},
"agentCreditGranted": {
"amount": "10.00",
"currency": "USD"
},
"agentCreditUsed": {
"amount": "4.20",
"currency": "USD"
},
"agentCreditBalance": {
"amount": "5.80",
"currency": "USD"
},
"amountStatus": "BILLING_AMOUNT_STATUS_PROVISIONAL"
},
"readTime": "2026-09-15T18:00:00Z"
}
{ "code": 16, "message": "unauthenticated" }
Returns the workspace’s credit balances and billed amounts for the current period. Amounts cover the whole workspace and are provisional.
Requires workspace Read. API keys can read only their bound workspace. No query parameters or pagination are supported. Excluded/deleted repositories and unattributed usage remain included.
Plan amounts and credit balances are not an atomic snapshot. An unavailable balance is not zero: check
balanceAvailable, which is omitted when false. Failed plan/balance reads fail the request; unknown plan currency returns 400 (FAILED_PRECONDITION). This operation does not initiate payments.
Authorization
string
required
Bearer <key>. See Authentication.Path parameters
string
required
GITHUB_ORGANIZATION or GITHUB_USER.string
required
Numeric GitHub ID of the organization or user.
Response
object
Show properties
Show properties
string
Start of the billing period (RFC 3339).
string
End of the billing period (RFC 3339).
boolean
false when balances could not be read. availableBalance and ledgerBalance are then omitted.Money
Credit available to spend.
Money
Recorded credit balance.
Money
Priced meter usage billed this period. Differs from the nominal cost reported by agent credit usage.
Money
Usage beyond the plan’s included amount.
Money
Amount due on the next invoice.
Money
Seat charges this period.
Money
Agent credit included in the plan this period.
Money
Agent credit used this period.
Money
Agent credit remaining.
string
Always
BILLING_AMOUNT_STATUS_PROVISIONAL. Amounts can change, including for past periods.string
When the response was generated (RFC 3339). Not a data freshness timestamp.
Money
An omitted Money object means no value, not zero.string
Decimal amount in major units, e.g.
"120.50". Cent values retain two decimals; USD centimill values retain five. Preserve decimal precision.string
ISO 4217 code, e.g.
"USD".curl https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/balance \
-H "Authorization: Bearer $MACROSCOPE_API_KEY"
import os, requests
r = requests.get(
"https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/balance",
headers={"Authorization": f"Bearer {os.environ['MACROSCOPE_API_KEY']}"},
)
print(r.json())
const res = await fetch(
"https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/balance",
{ headers: { Authorization: `Bearer ${process.env.MACROSCOPE_API_KEY}` } }
);
console.log(await res.json());
{
"balance": {
"periodStart": "2026-09-01T00:00:00Z",
"periodEnd": "2026-10-01T00:00:00Z",
"balanceAvailable": true,
"availableBalance": {
"amount": "120.50",
"currency": "USD"
},
"ledgerBalance": {
"amount": "500.00",
"currency": "USD"
},
"usageAmount": {
"amount": "379.50",
"currency": "USD"
},
"overageAmount": {
"amount": "0.00",
"currency": "USD"
},
"nextInvoiceAmountDue": {
"amount": "0.00",
"currency": "USD"
},
"seatAmount": {
"amount": "0.00",
"currency": "USD"
},
"agentCreditGranted": {
"amount": "10.00",
"currency": "USD"
},
"agentCreditUsed": {
"amount": "4.20",
"currency": "USD"
},
"agentCreditBalance": {
"amount": "5.80",
"currency": "USD"
},
"amountStatus": "BILLING_AMOUNT_STATUS_PROVISIONAL"
},
"readTime": "2026-09-15T18:00:00Z"
}
{ "code": 16, "message": "unauthenticated" }