list-gcp-billing-accounts
dci list-gcp-billing-accounts [flags]
Returns all GCP Billing Accounts accessible to the authenticated tenant. Use as the entry point to discover GCP billing account IDs, and billing-account-level onboarding status of the available product lines and savings metrics.
Each item includes metadata, CUD export health, trailing 30-day aggregate statistics, and precomputed YTD/lifetime savings totals per product line. Sum across items for customer-level totals.
Flags
| Flag | Type | Default | Example | Description |
|---|---|---|---|---|
--page-token | string | Opaque cursor token returned by a previous list response. Omit to start from the beginning; an empty or absent token in a response means there are no more results. Do not parse it. A structurally invalid cursor returns 400 with code pagination_token_invalid; an expired cursor returns 400 with code pagination_token_expired — restart pagination from the beginning. | ||
--max-results | integer | 50 | Maximum number of items to return. Server may return fewer. Defaults to 50; maximum 500. |
Every command also accepts the CLI-wide flags for output shaping — see Output formats and Table output options.
Output
List of GCP Billing Accounts. One item per billing account.
By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.
| Field | Type | Description |
|---|---|---|
items | array of object | |
items[].billingAccountId | string | GCP Billing Account ID. |
items[].displayName | string | Human-readable account name, if available. Defaults to the GCP Billing Account display name; may be overridden by a custom name set on the asset in the DoiT Console. Null when no name is available. |
items[].currency | string | ISO 4217 currency code for this billing account. |
items[].onboardingStatus | object | PerfectScale for Commitments onboarding status for each commitment type on the GCP billing account (compute). A commitment type is omitted when it is not onboarded. When done, inventory and recommendations for that commitment type are available. |
items[].onboardingStatus.compute | object | |
items[].onboardingStatus.compute.status | string | Current onboarding lifecycle stage for this product line. One of: "not_started", "onboarding", "done", "error". |
items[].onboardingStatus.compute.onboardingStartedAt | string (date-time) | When PerfectScale for Commitments first began tracking commitments for this commitment type. Bounds lifetime savings totals and onboarding history in the DoiT Console. Omitted or null when onboarding has not started. |
items[].cudExportHealthy | boolean | true if the BigQuery CUD export is healthy and up to date. |
items[].commitmentsSyncTime | string (date-time) | Timestamp of the last successful CUD inventory sync. Null when a sync has not completed yet. |
items[].stats30d | object | Trailing 30-day aggregate metrics (esr, savings), broken down by product line. |
items[].stats30d.compute | object | Minimal 30-day aggregate. Only esr and savings are persisted at this granularity. Responses are denominated in USD. |
items[].stats30d.compute.esr | number (double) | Effective Savings Rate (ESR) over the last 30 days, as a fraction from 0 to 1 (for example, 0.187 is 18.7%). Measures what share of eligible spend is saved through active commitments compared with equivalent on-demand cost. Higher ESR means greater realized savings. Null when not yet available. |
items[].stats30d.compute.savings | object | Total savings realized over the last 30 days from active commitments (USD). Nested fields omitted — see the raw JSON schema. |
items[].savingsTotals | object | Year-to-date and lifetime savings per product line. Same values as returned by GET /ps4commitments/v1/gcp/billing-accounts/\{billingAccountId\} for this billing account, so callers can sum totals across billing accounts without making an extra get-by-id call per billing account. Lifetime is bounded by each billing account's PerfectScale for Commitments onboarding start date. |
items[].savingsTotals.compute | object | Running savings figures derived server-side from the full monthly stats history, as the sum of onDemandCost - costWithSavings per month. lifetime starts at PerfectScale for Commitments onboarding; ytd starts at the later of January 1 of the current year and onboarding. Months before the bound are excluded; the bound month and the current month are prorated. |
items[].savingsTotals.compute.ytd | object | Year-to-date realized savings. Nested fields omitted — see the raw JSON schema. |
items[].savingsTotals.compute.lifetime | object | Lifetime realized savings since onboarding. Nested fields omitted — see the raw JSON schema. |
pageToken | string | |
rowCount | integer (int64) | Best-effort count for the filtered result set. May be null or omitted for expensive counts. |
Raw JSON schema
{
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"billingAccountId"
],
"properties": {
"billingAccountId": {
"type": "string",
"description": "GCP Billing Account ID.",
"example": "01D4A2-4E3F1B-9C72A0"
},
"displayName": {
"type": "string",
"description": "Human-readable account name, if available. Defaults to the GCP Billing Account display name; may be overridden by a custom name set on the asset in the DoiT Console. Null when no name is available.",
"nullable": true
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code for this billing account.",
"nullable": true,
"example": "USD"
},
"onboardingStatus": {
"allOf": [
{
"type": "object",
"description": "PerfectScale for Commitments onboarding status for each commitment type on the GCP billing account (`compute`). A commitment type is omitted when it is not onboarded. When `done`, inventory and recommendations for that commitment type are available.",
"properties": {
"compute": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Current onboarding lifecycle stage for this product line.",
"enum": [
"not_started",
"onboarding",
"done",
"error"
],
"x-enumDescriptions": {
"not_started": "This commitment type has not begun onboarding.",
"onboarding": "Onboarding is in progress (inventory and models still initializing).",
"done": "Onboarding completed, commitments and recommendations are available.",
"error": "Onboarding failed, check the DoiT Console or contact support for remediation."
}
},
"onboardingStartedAt": {
"type": "string",
"format": "date-time",
"description": "When PerfectScale for Commitments first began tracking commitments for this commitment type. Bounds lifetime savings totals and onboarding history in the DoiT Console. Omitted or null when onboarding has not started.",
"nullable": true
}
}
}
}
}
]
},
"cudExportHealthy": {
"type": "boolean",
"description": "`true` if the BigQuery CUD export is healthy and up to date.",
"nullable": true
},
"commitmentsSyncTime": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last successful CUD inventory sync. Null when a sync has not completed yet.",
"nullable": true
},
"stats30d": {
"type": "object",
"description": "Trailing 30-day aggregate metrics (`esr`, `savings`), broken down by product line.",
"properties": {
"compute": {
"type": "object",
"description": "Minimal 30-day aggregate. Only `esr` and `savings` are persisted at this granularity. Responses are denominated in USD.",
"properties": {
"esr": {
"type": "number",
"format": "double",
"description": "Effective Savings Rate (ESR) over the last 30 days, as a fraction from 0 to 1 (for example, `0.187` is 18.7%). Measures what share of eligible spend is saved through active commitments compared with equivalent on-demand cost. Higher ESR means greater realized savings. Null when not yet available.",
"nullable": true,
"example": 0.187
},
"savings": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "Total savings realized over the last 30 days from active commitments (USD)."
}
}
}
}
},
"savingsTotals": {
"type": "object",
"description": "Year-to-date and lifetime savings per product line. Same values as returned by `GET /ps4commitments/v1/gcp/billing-accounts/{billingAccountId}` for this billing account, so callers can sum totals across billing accounts without making an extra get-by-id call per billing account. Lifetime is bounded by each billing account's PerfectScale for Commitments onboarding start date.",
"properties": {
"compute": {
"type": "object",
"required": [
"ytd",
"lifetime"
],
"description": "Running savings figures derived server-side from the full monthly stats history, as the sum of `onDemandCost - costWithSavings` per month. `lifetime` starts at PerfectScale for Commitments onboarding; `ytd` starts at the later of January 1 of the current year and onboarding. Months before the bound are excluded; the bound month and the current month are prorated.",
"properties": {
"ytd": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "Year-to-date realized savings."
},
"lifetime": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "Lifetime realized savings since onboarding."
}
}
}
}
}
}
}
},
"pageToken": {
"type": "string",
"nullable": true
},
"rowCount": {
"type": "integer",
"format": "int64",
"description": "Best-effort count for the filtered result set. May be null or omitted for expensive counts.",
"nullable": true
}
}
}
Errors
On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.
HTTP status to exit code mapping
| HTTP status | Exit code | Error code | Meaning |
|---|---|---|---|
| 400 | 30 | VALIDATION_ERROR | The arguments or request body were rejected. Review the command's flags and payload. |
| 401 | 10 | AUTHENTICATION_FAILED | Not signed in, or the API token is invalid. Run dci login or check DCI_API_KEY. |
| 403 | 11 | PERMISSION_DENIED | The DoiT user or the active customer context does not have access. |
| 500, 503 | 40 | API_SERVER_ERROR | The API failed to process the request. Retryable; contact DoiT support if it persists. |
Related
- get-gcp-billing-account — Get a GCP billing account
- get-gcp-recommendation — Get a GCP recommendation
- list-gcp-billing-accounts-settings — List billing account engine settings
- list-gcp-planned-purchases — List GCP planned purchases
- list-gcp-recommendations — List GCP recommendations
- list-gcp-resource-cuds — List GCP resource-based Committed Use Discounts
- list-gcp-spend-cuds — List GCP spend-based Committed Use Discounts
- API reference: GET /ps4commitments/v1/gcp/billing-accounts
Aliases: listgcpbillingaccounts