Read the company credit balance
/company/creditsbilling:readRead the company credit balance. Only explicitly granted sites and permissions are accessible. No credentials or raw worker payloads are returned. Requires explicitly delegated company-wide billing:read; business-unit-restricted integrations are rejected. No date filters or credit mutations are supported.
| Request | GET https://satelliteai.io/api/v1/company/credits |
| Permission | billing:read |
| Response | A single object: data is CompanyCreditsData. |
| Operation ID | getCompanyCredits |
More context and worked examples are in the developer guide.
Example request
curl --fail-with-body \
'https://satelliteai.io/api/v1/company/credits' \
-H "Authorization: Bearer $SATELLITE_API_KEY"Replace the example IDs with values returned by the discovery endpoints. Example values are placeholders, not real records.
Parameters
No parameters. Send only the Authorization header.
Unknown or repeated query parameters return 400.
Data dictionary
Scoped result. Lists return pagination metadata; unavailable records return 404. Company balance. available_addon_credits sums currently active, positive, unexpired add-ons; available_credits adds max(base_credits_remaining, 0). addon_credits_remaining is the stored balance field. Period timestamps may omit a UTC suffix; as_of uses UTC Z.
[] marks an array element. nullable means the value can be null; treat it as unknown, not zero. always present means the key is always included in the object.
| Field | Type | Description |
|---|---|---|
data.company_id | integernullable | Company id. |
data.base_credits_remaining | integernullable | Base credits remaining. |
data.addon_credits_remaining | integernullable | Addon credits remaining. |
data.base_credit_allocation | integernullable | Base credit allocation. |
data.available_addon_credits | integernullable | Available addon credits. |
data.available_credits | integernullable | Available credits. |
data.current_period_start | stringnullable | Current period start. |
data.current_period_end | stringnullable | Current period end. |
data.last_reset_at | stringnullable | Last reset at. |
data.as_of | stringnullable | As of. |
Response metadata
| Field | Type | Description |
|---|---|---|
meta.request_id | stringalways present | Request identifier; also returned in X-Request-ID. Include it in support requests. |
meta.api_version | stringalways present | API version that produced the response. one of: v1 |
meta.limit | integer | Maximum records per page applied to this request. min 1 · max 100 |
meta.has_more | boolean | True when another page is available. |
meta.next_cursor | stringnullable | Opaque cursor for the next page; send as cursor. Null on the last page. |
meta.availability | string | available when stored data exists; not_available when it does not. one of: available, not_available |
meta.billing | object | Present for paid live SERP requests; replayed receipts describe the original debit, not an additional charge. |
meta.billing.operation | stringalways present | one of: client_api_serp_refresh |
meta.billing.credits_charged | integeralways present | min 0 |
meta.billing.transaction_id | integeralways present | |
meta.billing.replayed | booleanalways present |
Error responses
Errors return {"error": {"code", "message", "request_id"}}. See error handling for retry guidance.
| HTTP | When |
|---|---|
400 | Invalid parameters |
401 | Invalid credentials |
403 | Missing permission |
404 | Missing or inaccessible resource |