AI Billing
What an account’s AI work cost: the balance and the limits it is spent against, the immutable ledger of every charge, and the usage record of every attempt — kept for a key of your own too, where nothing is charged.
Get ai_billing
The account's AI balance, what it has spent today and this month, and the limits on that spending. Runs on the platform's key are paid from the balance and checked against the limits before they start; runs on the account's own provider key are not.
path Parameters
account_idId of the parent account.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get ai_billing › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
balanceThe AI balance as Money: what runs on the platform's key (MANAGED) are paid from. It is the balance after the latest row of ai_transactions, and it can be negative when runs started together spent past it.
currency_codeThe currency the balance, the limits and every charge are kept in (ISO 4217).
monthly_limitThe most the account may spend on the platform's key in a calendar month (UTC), as Money. A run that could take the month past it is refused before it starts. Leave it unset for no limit.
daily_limitThe most the account may spend on the platform's key in a calendar day (UTC), as Money. A run that could take the day past it is refused before it starts.
max_concurrent_executionsThe most runs the account may have queued or running at once, on any connection. A run created past it is refused with CONCURRENCY_LIMIT_REACHED.
platform_monthly_limitThe platform's monthly ceiling for this account, as Money. It applies over monthly_limit: the lower of the two is the one in force.
platform_daily_limitThe platform's daily ceiling for this account, as Money, in force over daily_limit.
platform_max_concurrent_executionsThe platform's ceiling on runs queued or running at once for this account, in force over max_concurrent_executions.
spend_todayWhat runs on the platform's key were charged today (UTC), as Money — the figure daily_limit is measured against.
spend_mtdWhat runs on the platform's key were charged this calendar month so far (UTC), as Money — the figure monthly_limit is measured against.
Update ai_billing
Sets the account's own limits on spending from the AI balance: monthly_limit and daily_limit as Money, and max_concurrent_executions. Clear a limit by naming it in update_mask with a null value. The balance cannot be changed here, and neither can the platform's ceilings shown beside the limits — the lower of each pair is the one in force.
path Parameters
account_idId of the parent account.
query Parameters
update_maskComma-separated field paths to merge. A field named here and sent as null is cleared; without the mask a null is dropped (§7, §11).
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Update ai_billing › Request Body
monthly_limitThe most the account may spend on the platform's key in a calendar month (UTC), as Money. A run that could take the month past it is refused before it starts. Leave it unset for no limit.
daily_limitThe most the account may spend on the platform's key in a calendar day (UTC), as Money. A run that could take the day past it is refused before it starts.
max_concurrent_executionsThe most runs the account may have queued or running at once, on any connection. A run created past it is refused with CONCURRENCY_LIMIT_REACHED.
Update ai_billing › Responses
The updated resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
balanceThe AI balance as Money: what runs on the platform's key (MANAGED) are paid from. It is the balance after the latest row of ai_transactions, and it can be negative when runs started together spent past it.
currency_codeThe currency the balance, the limits and every charge are kept in (ISO 4217).
monthly_limitThe most the account may spend on the platform's key in a calendar month (UTC), as Money. A run that could take the month past it is refused before it starts. Leave it unset for no limit.
daily_limitThe most the account may spend on the platform's key in a calendar day (UTC), as Money. A run that could take the day past it is refused before it starts.
max_concurrent_executionsThe most runs the account may have queued or running at once, on any connection. A run created past it is refused with CONCURRENCY_LIMIT_REACHED.
platform_monthly_limitThe platform's monthly ceiling for this account, as Money. It applies over monthly_limit: the lower of the two is the one in force.
platform_daily_limitThe platform's daily ceiling for this account, as Money, in force over daily_limit.
platform_max_concurrent_executionsThe platform's ceiling on runs queued or running at once for this account, in force over max_concurrent_executions.
spend_todayWhat runs on the platform's key were charged today (UTC), as Money — the figure daily_limit is measured against.
spend_mtdWhat runs on the platform's key were charged this calendar month so far (UTC), as Money — the figure monthly_limit is measured against.
List ai_transactions
The account's AI ledger: every charge for a run on the platform's key and every change the platform made to the balance, newest first. Rows are never edited or deleted — a correction is a row of its own.
path Parameters
account_idId of the parent account.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: create_time desc. Sortable: create_time.
filterAIP-160 subset (§8). Filterable: create_time, execution_id, pricing_id, type, usage_record_id. A field outside the list is INVALID_ARGUMENT.
List ai_transactions › Responses
One page of ai_transactions.
This page of ai_transactions, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Get ai_transaction
The account's AI ledger: every charge for a run on the platform's key and every change the platform made to the balance, newest first. Rows are never edited or deleted — a correction is a row of its own.
path Parameters
account_idId of the parent account.
ai_transaction_idId of the parent ai_transaction.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get ai_transaction › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
typeCHARGE for a run on the platform's key; TOP_UP, REFUND, ADJUSTMENT or BONUS for a change made by the platform.
amountThe row's amount as Money, signed: negative for a charge, positive for money put in.
balance_afterThe balance right after this row, as Money, so a statement reads without adding up the rows before it.
execution_idThe ai_executions entry a CHARGE is for. Absent on every other type.
usage_record_idThe ai_usage_records entry — the attempt and its token counts — a CHARGE was priced from.
pricing_idThe price row a CHARGE was priced at. Price rows never change, so a later price change does not restate it.
descriptionWhat the row is for, in words: the run and attempt of a charge, or the reason given for a change.
List ai_usage_records
What each attempt of the account's AI runs consumed, in tokens — for runs on the account's own provider key as much as for runs charged to the balance. One entry per attempt whose token counts the provider reported, newest first.
path Parameters
account_idId of the parent account.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: create_time desc. Sortable: create_time.
filterAIP-160 subset (§8). Filterable: agent_id, connection_mode, create_time, execution_id, model_id, provider. A field outside the list is INVALID_ARGUMENT.
List ai_usage_records › Responses
One page of ai_usage_records.
This page of ai_usage_records, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Get ai_usage_record
What each attempt of the account's AI runs consumed, in tokens — for runs on the account's own provider key as much as for runs charged to the balance. One entry per attempt whose token counts the provider reported, newest first.
path Parameters
account_idId of the parent account.
ai_usage_record_idId of the parent ai_usage_record.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get ai_usage_record › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
execution_idThe ai_executions entry the attempt belongs to.
attemptThe number of the attempt within its run, as in the run's attempts.
agent_idThe ai_agents entry the run executed.
model_idThe ai_models entry the attempt ran on.
providerThe AI provider that served the attempt, by the platform's name for it.
connection_modeWhose key the attempt used: BYOK (the account's own, billed by the provider) or MANAGED (the platform's, charged to the AI balance).
input_tokensInput tokens the provider counted for the attempt, cache reads and writes not included.
output_tokensOutput tokens the provider counted for the attempt.
cache_read_input_tokensInput tokens the provider served from its prompt cache.
cache_creation_input_tokensInput tokens the provider wrote to its prompt cache.
raw_usageThe provider's own usage object for the attempt, exactly as it arrived, kept beside the four counters above.