Get the billing overview

The organization's billing status, balance, active plans, allowances and what it spent this month.

Scopes: any one of account:billing:read, account:billing:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: read-only; safe to retry
Limits: response up to 256 KB
CLI: arbol account billing get · MCP tool: account_billing_get

GET

https://api.getarbol.com/v1/account/billing

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with any one of the scopes account:billing:read, account:billing:write. Get an API key.

Returns

200

Successful operation.

JSON

success
true
required
data
object
required
- status
  trialing
  or
  active
  or
  past_due
  or
  suspended
  or
  closed
  required
- billingMode
  prepaid
  or
  postpaid
  required
- suspendedReason
  wallet_exhausted
  or
  past_due
  or
  manual
  or
  null
  required
- wallet
  object
  required
  balanceMicros
  integer
  required
  Micros of the currency named with it.
  
  currency
  string
  required
  creditLimitMicros
  integer
  required
  Micros of the currency named with it.
  
  unlimitedCredit
  boolean
  required
  lowBalanceThresholdMicros
  integer
  required
  Micros of the currency named with it.
- subscriptions
  array of
  object
  required
  id
  string
  required
  planSlug
  string
  required
  planVersion
  integer
  required
  kind
  recurring
  or
  pack
  required
  status
  active
  or
  ended
  required
  startsAt
  string
  required
  format: date-time
  endsAt
  string | null
  required
  format: date-time
  currentPeriodStartsAt
  string | null
  required
  format: date-time
  currentPeriodEndsAt
  string | null
  required
  format: date-time
  currentPeriodStart
  deprecated
  string | null
  required
  Deprecated: use currentPeriodStartsAt. Answered until 2027-01-28.
  
  format: date-time
  currentPeriodEnd
  deprecated
  string | null
  required
  Deprecated: use currentPeriodEndsAt. Answered until 2027-01-28.
  
  format: date-time
  cancelAt
  string | null
  required
  format: date-time
- balances
  array of
  object
  required
  meter
  string
  required
  unit
  string
  required
  kind
  consumable
  or
  gauge
  required
  remaining
  number
  required
  What is left in meter units.
  
  creditRemainingMicros
  integer
  required
  Micros of the currency named with it.
  
  limit
  number | null
  required
- monthToDate
  object
  required
  startsAt
  string
  required
  format: date-time
  endsAt
  string
  required
  format: date-time
  priceMicros
  integer
  required
  Micros of the currency named with it.
  
  start
  deprecated
  string
  required
  Deprecated: use startsAt. Answered until 2027-01-28.
  
  format: date-time
  end
  deprecated
  string
  required
  Deprecated: use endsAt. Answered until 2027-01-28.
  
  format: date-time
- profileComplete
  boolean
  required
  Whether the billing profile has what invoices need.
}
error
unknown
required
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.

JSON

success
false
required
data
unknown
required
error
object
required
The request does not match the published schema.
- code
  INVALID_INPUT
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  issues
  optional
  array of
  object
  path
  string
  required
  RFC 6901 JSON Pointer to the refused field; empty for the whole input.
  
  maxLength: 256
  message
  string
  required
  maxLength: 256
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

401

UNAUTHORIZED: A valid access token is required.

JSON

success
false
required
data
unknown
required
error
object
required
A valid access token is required.
- code
  UNAUTHORIZED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

403

FORBIDDEN: The token does not authorize this operation.

JSON

success
false
required
data
unknown
required
error
object
required
The token does not authorize this operation.
- code
  FORBIDDEN
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

404

BILLING_RECORD_NOT_FOUND: Billing has no such record.

JSON

success
false
required
data
unknown
required
error
object
required
Billing has no such record.
- code
  BILLING_RECORD_NOT_FOUND
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

409

BILLING_REJECTED: Billing refused the request.

JSON

success
false
required
data
unknown
required
error
object
required
Billing refused the request.
- code
  BILLING_REJECTED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

success
false
required
data
unknown
required
error
object
required
The request rate limit was exceeded. Try again later.
- code
  RATE_LIMITED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  true
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

success
false
required
data
unknown
required
error
object
required
The service could not complete the operation.
- code
  INTERNAL_ERROR
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.

JSON

success
false
required
data
unknown
required
error
object
required
The operation may have been applied; check its result before repeating it.
- code
  OUTCOME_UNKNOWN
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
BILLING_UNAVAILABLE: Billing did not answer.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
UpstreamUnavailableFailure
UPSTREAM_UNAVAILABLE
code
UPSTREAM_UNAVAILABLE
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
true
required
Whether repeating the same request may succeed.

data
object
required
No fields.

AccountBillingUnavailableFailure
BILLING_UNAVAILABLE
code
BILLING_UNAVAILABLE
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
true
required
Whether repeating the same request may succeed.

data
object
required
No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

success
false
required
data
unknown
required
error
object
required
The upstream service did not respond before its deadline.
- code
  UPSTREAM_TIMEOUT
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  true
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}