get-allocation
dci get-allocation <id>
Returns an allocation by the specified Id.
id— Allocation ID or name as shown bydci list-allocations. Names resolve (exact, unique substring, or close typo); pass--idto force a literal ID.
Examples
# Show one allocation and its rule.
dci get-allocation "Team Backyard"
# The full record as JSON, for scripts or as the starting point of an update-allocation body.
dci get-allocation <allocation-id> --output json
# Only the fields you need.
dci get-allocation <allocation-id> --fields name,allocationType,rule --output json
Output
OK - Allocation returned.
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 |
|---|---|---|
id | string | Allocation ID. |
name | string | Allocation name. |
description | string | Allocation description. |
type | string | Type of allocation (preset or custom). |
allocationType | string | Composition type of allocation. One of: "single", "group". |
createTime | integer (int64) | The time when the allocation was created (in UNIX timestamp). |
updateTime | integer (int64) | Last time the allocation was modified (in UNIX timestamp). |
anomalyDetection | boolean | Whether anomaly detection is enabled for this allocation. Only applicable to single allocations. |
rule | object | Single allocation rule. Components can reference other existing allocation rules by using the "allocation_rule" dimension type. |
rule.components | array of object | List of allocation filter components. |
rule.components[].key | string | Key of an existing dimension. Examples: "billing_account_id", "country". When type is "allocation_rule", the key must be set to "allocation_rule". Use GET /analytics/v1/dimensions to retrieve all available dimensions. |
rule.components[].type | string | Dimension filter type for allocation rule components. See DimensionsTypes for per-value meanings. Allocation components do not support allocation, attribution, or attribution_group types. One of: "datetime", "fixed", "optional", "label", "tag", "project_label", "system_label", "allocation_rule", "gke", "gke_label". |
rule.components[].values | array of string | Values to filter on. When type is "allocation_rule", the values are IDs of existing allocation rules. |
rule.components[].inverse | boolean | If true, all selected values will be excluded. Default: false. |
rule.components[].includeNull | boolean | Include null values. Default: false. |
rule.components[].caseInsensitive | boolean | If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise. Default: false. |
rule.components[].mode | string | Filter mode to apply. When type is "allocation_rule", only "is" and "contains" modes are supported. One of: "is", "starts_with", "ends_with", "contains", "regexp". |
rule.formula | string | Formula for combining components (A is the first component, B is the second one, etc.). |
rule.validityPeriods | array of object | Ordered, non-overlapping date ranges when this rule applies. Empty or absent means the rule always applies. |
rule.validityPeriods[].startDate | string | Start date (YYYY-MM-DD, UTC), inclusive. Absent means no lower bound. |
rule.validityPeriods[].endDate | string | End date (YYYY-MM-DD, UTC), inclusive. Absent means no upper bound. |
rules | array of object | |
rules[].name | string | Name of the allocation rule. |
rules[].description | string | Description of the allocation rule. |
rules[].action | string | Action to perform with this rule. One of: "create", "update", "select". |
rules[].id | string | ID of existing allocation (required for 'update' or 'select' action). |
rules[].components | array of object | List of allocation filter components (required for 'create' or 'update' action). Can include components of type "allocation_rule" to reference existing allocation rules. |
rules[].components[].key | string | Key of an existing dimension. Examples: "billing_account_id", "country". When type is "allocation_rule", the key must be set to "allocation_rule". Use GET /analytics/v1/dimensions to retrieve all available dimensions. |
rules[].components[].type | string | Dimension filter type for allocation rule components. See DimensionsTypes for per-value meanings. Allocation components do not support allocation, attribution, or attribution_group types. One of: "datetime", "fixed", "optional", "label", "tag", "project_label", "system_label", "allocation_rule", "gke", "gke_label". |
rules[].components[].values | array of string | Values to filter on. When type is "allocation_rule", the values are IDs of existing allocation rules. |
rules[].components[].inverse | boolean | If true, all selected values will be excluded. Default: false. |
rules[].components[].includeNull | boolean | Include null values. Default: false. |
rules[].components[].caseInsensitive | boolean | If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise. Default: false. |
rules[].components[].mode | string | Filter mode to apply. When type is "allocation_rule", only "is" and "contains" modes are supported. One of: "is", "starts_with", "ends_with", "contains", "regexp". |
rules[].formula | string | Formula for combining components (A is the first component, B is the second one, etc.) |
rules[].valueExtraction | object | Makes the rule emit a value extracted from the first non-empty source instead of the rule name. |
rules[].valueExtraction.sources | array of object | Ordered extraction sources; the first non-empty value wins. |
rules[].valueExtraction.sources[].type | string | The dimension type to read the value from. Label-map types (label, tag, project_label, system_label, gke_label) extract the value of the given key; "fixed" extracts a raw table dimension (for example project_id, service_description, region). Derived dimensions such as credits are not extractable. One of: "label", "tag", "project_label", "system_label", "gke_label", "fixed". |
rules[].valueExtraction.sources[].key | string | The label/tag key, or the fixed dimension ID, whose value is extracted. |
rules[].valueExtraction.sources[].providers | array of string | Optional cloud providers this source applies to. |
rules[].valueExtraction.onMissing | string | What happens when every source is missing or empty on a matching row. "useFallback" (default) emits the fallback value, which is required in that mode; "nextRule" lets the row fall through to the next rule in the group. One of: "useFallback", "nextRule". Default: "useFallback". |
rules[].valueExtraction.fallback | string | Literal emitted when every source is missing. Required with onMissing "useFallback" (the default); not allowed with onMissing "nextRule". |
rules[].validityPeriods | array of object | Ordered, non-overlapping date ranges when this rule applies. Empty or absent means the rule always applies. |
rules[].validityPeriods[].startDate | string | Start date (YYYY-MM-DD, UTC), inclusive. Absent means no lower bound. |
rules[].validityPeriods[].endDate | string | End date (YYYY-MM-DD, UTC), inclusive. Absent means no upper bound. |
unallocatedCosts | string | Custom label for values that do not fit into allocation (required for group type allocation). |
folderId | string | Identifier of the folder that contains the allocation. Set to "root" if the allocation is at the top level (not in a folder). Default: "root". |
Raw JSON schema
{
"type": "object",
"description": "Allocation object, including rules and metadata.",
"properties": {
"id": {
"type": "string",
"description": "Allocation ID."
},
"name": {
"type": "string",
"description": "Allocation name."
},
"description": {
"type": "string",
"description": "Allocation description."
},
"type": {
"type": "string",
"description": "Type of allocation (preset or custom)."
},
"allocationType": {
"type": "string",
"description": "Composition type of allocation.",
"enum": [
"single",
"group"
]
},
"createTime": {
"type": "integer",
"description": "The time when the allocation was created (in UNIX timestamp).",
"format": "int64"
},
"updateTime": {
"type": "integer",
"description": "Last time the allocation was modified (in UNIX timestamp).",
"format": "int64"
},
"anomalyDetection": {
"type": "boolean",
"description": "Whether anomaly detection is enabled for this allocation. Only applicable to single allocations."
},
"rule": {
"required": [
"components",
"formula"
],
"type": "object",
"description": "Single allocation rule. Components can reference other existing allocation rules by using the \"allocation_rule\" dimension type.",
"nullable": true,
"properties": {
"components": {
"type": "array",
"description": "List of allocation filter components.",
"items": {
"required": [
"key",
"type",
"values",
"mode"
],
"type": "object",
"description": "A filter component used inside allocation rules.\nWhen the type is \"allocation_rule\", the component references existing allocation rules (nested allocation rules).\nA maximum nesting depth of 3 levels is supported, and circular references are not allowed.",
"properties": {
"key": {
"type": "string",
"description": "Key of an existing dimension. Examples: \"billing_account_id\", \"country\". When type is \"allocation_rule\", the key must be set to \"allocation_rule\".\nUse `GET /analytics/v1/dimensions` to retrieve all available dimensions."
},
"type": {
"description": "Dimension filter type for allocation rule components. See `DimensionsTypes` for per-value meanings. Allocation components do not support `allocation`, `attribution`, or `attribution_group` types.",
"type": "string",
"enum": [
"datetime",
"fixed",
"optional",
"label",
"tag",
"project_label",
"system_label",
"allocation_rule",
"gke",
"gke_label"
],
"x-enumDescriptions": {
"fixed": "Standard built-in billing dimensions.",
"label": "Customer-defined resource labels; key is the label key.",
"tag": "AWS cost allocation tags; key is the tag key.",
"project_label": "Google Cloud project-level labels.",
"system_label": "DoiT- or provider-generated system labels.",
"optional": "Console grouping for label/tag keys; use a concrete subtype in filters.",
"datetime": "Time dimensions for date-based filtering.",
"allocation_rule": "Reference another allocation rule by ID.",
"gke": "Google Kubernetes Engine cost-allocation dimensions.",
"gke_label": "GKE workload labels."
}
},
"values": {
"type": "array",
"description": "Values to filter on. When type is \"allocation_rule\", the values are IDs of existing allocation rules.",
"items": {
"type": "string"
}
},
"inverse": {
"type": "boolean",
"description": "If true, all selected values will be excluded.",
"default": false
},
"includeNull": {
"type": "boolean",
"description": "Include null values.",
"default": false
},
"caseInsensitive": {
"type": "boolean",
"description": "If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise.",
"default": false
},
"mode": {
"type": "string",
"description": "Filter mode to apply. When type is \"allocation_rule\", only \"is\" and \"contains\" modes are supported.",
"enum": [
"is",
"starts_with",
"ends_with",
"contains",
"regexp"
]
}
}
}
},
"formula": {
"type": "string",
"description": "Formula for combining components (A is the first component, B is the second one, etc.).",
"example": "A AND B"
},
"validityPeriods": {
"type": "array",
"nullable": true,
"description": "Ordered, non-overlapping date ranges when this rule applies. Empty or absent means the rule always applies.",
"items": {
"type": "object",
"description": "A date range when a rule applies. startDate and endDate are both inclusive, so a handover between two rules needs a one-day gap: the first rule's endDate the day before, the second rule's startDate the handover day. Only the first period in the list may omit startDate, and only the last may omit endDate.",
"properties": {
"startDate": {
"type": "string",
"nullable": true,
"description": "Start date (YYYY-MM-DD, UTC), inclusive. Absent means no lower bound.",
"example": "2026-03-15"
},
"endDate": {
"type": "string",
"nullable": true,
"description": "End date (YYYY-MM-DD, UTC), inclusive. Absent means no upper bound.",
"example": "2026-06-15"
}
}
}
}
}
},
"rules": {
"type": "array",
"items": {
"required": [
"action"
],
"type": "object",
"nullable": true,
"description": "Allocation rule for a group type allocation. Components can reference other existing allocation rules by using the \"allocation_rule\" dimension type.",
"properties": {
"name": {
"type": "string",
"description": "Name of the allocation rule."
},
"description": {
"type": "string",
"description": "Description of the allocation rule."
},
"action": {
"type": "string",
"description": "Action to perform with this rule.",
"enum": [
"create",
"update",
"select"
]
},
"id": {
"type": "string",
"description": "ID of existing allocation (required for 'update' or 'select' action)."
},
"components": {
"type": "array",
"description": "List of allocation filter components (required for 'create' or 'update' action). Can include components of type \"allocation_rule\" to reference existing allocation rules.",
"items": {
"required": [
"key",
"type",
"values",
"mode"
],
"type": "object",
"description": "A filter component used inside allocation rules.\nWhen the type is \"allocation_rule\", the component references existing allocation rules (nested allocation rules).\nA maximum nesting depth of 3 levels is supported, and circular references are not allowed.",
"properties": {
"key": {
"type": "string",
"description": "Key of an existing dimension. Examples: \"billing_account_id\", \"country\". When type is \"allocation_rule\", the key must be set to \"allocation_rule\".\nUse `GET /analytics/v1/dimensions` to retrieve all available dimensions."
},
"type": {
"description": "Dimension filter type for allocation rule components. See `DimensionsTypes` for per-value meanings. Allocation components do not support `allocation`, `attribution`, or `attribution_group` types.",
"type": "string",
"enum": [
"datetime",
"fixed",
"optional",
"label",
"tag",
"project_label",
"system_label",
"allocation_rule",
"gke",
"gke_label"
],
"x-enumDescriptions": {
"fixed": "Standard built-in billing dimensions.",
"label": "Customer-defined resource labels; key is the label key.",
"tag": "AWS cost allocation tags; key is the tag key.",
"project_label": "Google Cloud project-level labels.",
"system_label": "DoiT- or provider-generated system labels.",
"optional": "Console grouping for label/tag keys; use a concrete subtype in filters.",
"datetime": "Time dimensions for date-based filtering.",
"allocation_rule": "Reference another allocation rule by ID.",
"gke": "Google Kubernetes Engine cost-allocation dimensions.",
"gke_label": "GKE workload labels."
}
},
"values": {
"type": "array",
"description": "Values to filter on. When type is \"allocation_rule\", the values are IDs of existing allocation rules.",
"items": {
"type": "string"
}
},
"inverse": {
"type": "boolean",
"description": "If true, all selected values will be excluded.",
"default": false
},
"includeNull": {
"type": "boolean",
"description": "Include null values.",
"default": false
},
"caseInsensitive": {
"type": "boolean",
"description": "If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise.",
"default": false
},
"mode": {
"type": "string",
"description": "Filter mode to apply. When type is \"allocation_rule\", only \"is\" and \"contains\" modes are supported.",
"enum": [
"is",
"starts_with",
"ends_with",
"contains",
"regexp"
]
}
}
}
},
"formula": {
"type": "string",
"description": "Formula for combining components (A is the first component, B is the second one, etc.)",
"example": "A AND B"
},
"valueExtraction": {
"type": "object",
"nullable": true,
"required": [
"sources"
],
"description": "Makes the rule emit a value extracted from the first non-empty source instead of the rule name.",
"properties": {
"sources": {
"type": "array",
"minItems": 1,
"maxItems": 5,
"description": "Ordered extraction sources; the first non-empty value wins.",
"items": {
"type": "object",
"required": [
"type",
"key"
],
"properties": {
"type": {
"type": "string",
"description": "The dimension type to read the value from. Label-map types (label, tag, project_label, system_label, gke_label) extract the value of the given key; \"fixed\" extracts a raw table dimension (for example project_id, service_description, region). Derived dimensions such as credits are not extractable.",
"enum": [
"label",
"tag",
"project_label",
"system_label",
"gke_label",
"fixed"
]
},
"key": {
"type": "string",
"description": "The label/tag key, or the fixed dimension ID, whose value is extracted."
},
"providers": {
"type": "array",
"nullable": true,
"description": "Optional cloud providers this source applies to.",
"items": {
"type": "string"
}
}
}
}
},
"onMissing": {
"type": "string",
"description": "What happens when every source is missing or empty on a matching row. \"useFallback\" (default) emits the fallback value, which is required in that mode; \"nextRule\" lets the row fall through to the next rule in the group.",
"enum": [
"useFallback",
"nextRule"
],
"default": "useFallback"
},
"fallback": {
"type": "string",
"nullable": true,
"description": "Literal emitted when every source is missing. Required with onMissing \"useFallback\" (the default); not allowed with onMissing \"nextRule\"."
}
}
},
"validityPeriods": {
"type": "array",
"nullable": true,
"description": "Ordered, non-overlapping date ranges when this rule applies. Empty or absent means the rule always applies.",
"items": {
"type": "object",
"description": "A date range when a rule applies. startDate and endDate are both inclusive, so a handover between two rules needs a one-day gap: the first rule's endDate the day before, the second rule's startDate the handover day. Only the first period in the list may omit startDate, and only the last may omit endDate.",
"properties": {
"startDate": {
"type": "string",
"nullable": true,
"description": "Start date (YYYY-MM-DD, UTC), inclusive. Absent means no lower bound.",
"example": "2026-03-15"
},
"endDate": {
"type": "string",
"nullable": true,
"description": "End date (YYYY-MM-DD, UTC), inclusive. Absent means no upper bound.",
"example": "2026-06-15"
}
}
}
}
}
}
},
"unallocatedCosts": {
"type": "string",
"description": "Custom label for values that do not fit into allocation (required for group type allocation).",
"nullable": true
},
"folderId": {
"type": "string",
"description": "Identifier of the folder that contains the allocation. Set to \"root\" if the allocation is at the top level (not in a folder).",
"default": "root",
"example": "root"
}
}
}
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. |
| 404 | 20 | RESOURCE_NOT_FOUND | The requested resource does not exist. Check the identifier argument. |
Related
- list-allocations — List allocations
- create-allocation — Create an allocation
- update-allocation — Update an allocation
- delete-allocation — Delete an allocation
- API reference: GET /analytics/v1/allocations/{id}
Aliases: getallocation