---
updatedAt: 2026-09-09T12:37:08.000Z
agentTools:
  projectIndex: https://developer.doit.com/llms.txt
---

# Get a GCP recommendation

Returns the recommendation for one product line (`gcp_service`) and region scope on the GCP
billing account, including analysis metrics and time-bucketed eligible spend. Use
`granularity` to choose the eligible-spend bucket size (defaults to `day`).

**`region`**: optional for `compute`, defaulting to `global` (its only scope). Required
for `cloud_sql` — omitting it returns `400` with code `validation_failed`, as does a
malformed region or one incompatible with `gcp_service` (`cloud_sql` never uses `global`).
A well-formed region the billing account has never had eligible spend in returns `404`
with code `not_found` — the scope does not exist, same as an unknown billing account.
When the scope exists but no stored recommendation matches, the response is `200` with
`recommendation` omitted and `estimatedEquivalentRecommendedCommitment` of `0`.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "DoiT Cloud Intelligence",
    "description": "Programmatic access to DoiT Platform",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://api.doit.com"
    }
  ],
  "security": [
    {
      "api_key": []
    },
    {
      "tenantId": [],
      "api_key": []
    }
  ],
  "tags": [
    {
      "name": "PerfectScale for Commitments GCP",
      "description": "Evaluate current GCP commitments, plan and automate purchases, and optimize cloud costs with PerfectScale for Commitments."
    }
  ],
  "paths": {
    "/ps4commitments/v1/gcp/billing-accounts/{billingAccountId}/recommendations/{gcp_service}": {
      "get": {
        "operationId": "getGcpRecommendation",
        "tags": [
          "PerfectScale for Commitments GCP"
        ],
        "summary": "Get a GCP recommendation",
        "description": "Returns the recommendation for one product line (`gcp_service`) and region scope on the GCP\nbilling account, including analysis metrics and time-bucketed eligible spend. Use\n`granularity` to choose the eligible-spend bucket size (defaults to `day`).\n\n**`region`**: optional for `compute`, defaulting to `global` (its only scope). Required\nfor `cloud_sql` — omitting it returns `400` with code `validation_failed`, as does a\nmalformed region or one incompatible with `gcp_service` (`cloud_sql` never uses `global`).\nA well-formed region the billing account has never had eligible spend in returns `404`\nwith code `not_found` — the scope does not exist, same as an unknown billing account.\nWhen the scope exists but no stored recommendation matches, the response is `200` with\n`recommendation` omitted and `estimatedEquivalentRecommendedCommitment` of `0`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/tenantId"
          },
          {
            "$ref": "#/components/parameters/billingAccountId"
          },
          {
            "name": "gcp_service",
            "in": "path",
            "required": true,
            "description": "PS4C product line to fetch the recommendation for. Matching is case-insensitive; the value is lowercased before validation.",
            "schema": {
              "type": "string",
              "enum": [
                "compute",
                "cloud_sql"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/gcp_region"
          },
          {
            "$ref": "#/components/parameters/eligibleSpendGranularity"
          }
        ],
        "responses": {
          "200": {
            "description": "Recommendation detail with eligible-spend usage series.",
            "headers": {
              "Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Content-Language": {
                "$ref": "#/components/headers/ContentLanguage"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GcpRecommendationWithEligibleSpend"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "GcpRegion": {
        "type": "string",
        "pattern": "^(global|[a-z]+(_[a-z0-9]+)+)$",
        "description": "GCP region scope in the DCI `lower_snake_case` wire form (for example `us_east1`), or the\nliteral `global` for cross-region scopes. This is not the raw provider spelling (`us-east1`);\nthe same pattern applies to the `region` query parameter. Regions are discovery-driven, so the\nlist is open rather than an enum.",
        "example": "us_east1"
      },
      "GcpRecommendation": {
        "type": "object",
        "description": "A CUD purchase recommendation for a (service, region) scope.",
        "properties": {
          "policy": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CommitmentPolicyId"
              }
            ],
            "description": "Coverage target policy configured for this product line and region scope (built-in or customer-defined)."
          },
          "region": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GcpRegion"
              }
            ],
            "description": "Region scope for this recommendation, in `lower_snake_case` wire form (for example `us_east1`). `global` for `compute`; a concrete region for `cloud_sql`."
          },
          "service": {
            "type": "string",
            "enum": [
              "compute",
              "cloud_sql"
            ],
            "description": "PS4C product line (`gcp_service`) this recommendation belongs to."
          },
          "currentCommitment": {
            "type": "number",
            "format": "double",
            "description": "Active hourly commitment ($/h) currently applied to this billing account and product line, including commitments already purchased."
          },
          "recommendedCommitment": {
            "type": "number",
            "format": "double",
            "description": "Recommended total hourly commitment ($/h) based on usage patterns and your commitment policy. Designed to increase savings while managing underutilization risk."
          },
          "potentialAdditionalSavings": {
            "type": "number",
            "format": "double",
            "description": "Estimated additional monthly savings ($/month) from applying the recommended commitment relative to `currentCommitment`."
          },
          "estimatedAverageCoverage": {
            "type": "number",
            "format": "double",
            "minimum": 0,
            "maximum": 1,
            "description": "Estimated average coverage of eligible spend if the recommended commitment were in place, as a fraction from 0 to 1 (for example, `0.5517` is 55.17%). Same scale as `esr` and the inventory utilization and coverage fields."
          }
        }
      },
      "GcpRecommendationWithEligibleSpend": {
        "type": "object",
        "description": "A single GCP recommendation paired with its eligible-spend usage series.",
        "properties": {
          "estimatedEquivalentRecommendedCommitment": {
            "type": "number",
            "format": "double",
            "description": "Shelf-price hourly equivalent ($/h) of the recommended commitment, derived from the median hourly eligible usage over the trailing window multiplied by `estimatedAverageCoverage`. Use this to compare the recommendation line to eligible usage on charts."
          },
          "recommendation": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GcpRecommendation"
              }
            ],
            "description": "Recommended commitment metrics for the requested (service, region) scope."
          },
          "eligibleUsage": {
            "type": "array",
            "description": "Eligible spend over time at the requested `granularity`. Empty when no eligible usage exists in the trailing window.",
            "items": {
              "$ref": "#/components/schemas/EligibleSpendDataPoint"
            }
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code",
          "retryable"
        ],
        "additionalProperties": true,
        "description": "RFC 9457 Problem Details — standard DoiT error envelope for all non-2xx responses.",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "example": "https://developer.doit.com/errors/not_found"
          },
          "title": {
            "type": "string",
            "example": "Resource not found"
          },
          "status": {
            "type": "integer",
            "example": 404
          },
          "detail": {
            "type": "string",
            "example": "customer not found"
          },
          "instance": {
            "type": "string",
            "format": "uri",
            "example": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9"
          },
          "code": {
            "type": "string",
            "pattern": "^([a-z][a-z0-9_]*|[a-z][a-z0-9]*(?:-[a-z0-9]+)*\\.[a-z][a-z0-9_]*)$",
            "example": "not_found"
          },
          "retryable": {
            "type": "boolean",
            "example": false
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "issue"
              ],
              "properties": {
                "issue": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9_]*$"
                },
                "field": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          },
          "docsUrl": {
            "type": "string",
            "format": "uri",
            "nullable": true
          }
        }
      },
      "CommitmentPolicyId": {
        "type": "string",
        "description": "ID of a commitment policy: either one of the built-in policies — `conservative` (lower\ncoverage target, ~65%), `balanced` (moderate, ~80%), `max_savings` (aggressive, ~90%) — or the\nID of a policy the customer defined in the DoiT Console. One catalog is shared by AWS and GCP,\nand the same policy may be assigned to any AWS organization or GCP billing account product\nline. Custom policies make this an open list, so it is not an enum; treat the value as an\nopaque identifier and use the commitment-policies endpoint to resolve it.",
        "example": "balanced"
      },
      "EligibleSpendDataPoint": {
        "type": "object",
        "description": "One time-bucketed eligible-spend usage point for the recommendation chart. Units are shelf-price hourly dollars ($/h) unless noted by the client visualization.",
        "properties": {
          "usageTime": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the time bucket for this data point (UTC).",
            "nullable": true
          },
          "totalUsage": {
            "type": "number",
            "format": "double",
            "description": "Total eligible usage in the bucket when granularity is `hour`. Prefer min/max/median for coarser granularities."
          },
          "minUsage": {
            "type": "number",
            "format": "double",
            "description": "Minimum eligible usage ($/h) observed in the bucket (day/week/month views)."
          },
          "maxUsage": {
            "type": "number",
            "format": "double",
            "description": "Maximum eligible usage ($/h) observed in the bucket (day/week/month views)."
          },
          "medianUsage": {
            "type": "number",
            "format": "double",
            "description": "Median eligible usage ($/h) observed in the bucket (day/week/month views)."
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Syntactically malformed request, missing required parameter, or unsupported parameter value.",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Content-Language": {
            "$ref": "#/components/headers/ContentLanguage"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "examples": {
              "validationFailed": {
                "summary": "Missing or invalid parameter",
                "value": {
                  "type": "https://developer.doit.com/errors/validation_failed",
                  "title": "Validation failed",
                  "status": 400,
                  "detail": "The request is missing a required parameter or contains an invalid value.",
                  "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
                  "code": "validation_failed",
                  "retryable": false
                }
              },
              "tenantIdRequired": {
                "summary": "Tenant scope not resolvable",
                "value": {
                  "type": "https://developer.doit.com/errors/tenant_id_required",
                  "title": "Tenant ID required",
                  "status": 400,
                  "detail": "X-Tenant-Id header is required when the credential can access more than one tenant.",
                  "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
                  "code": "tenant_id_required",
                  "retryable": false
                }
              },
              "tenantIdMismatch": {
                "summary": "Header conflicts with the key's tenant",
                "value": {
                  "type": "https://developer.doit.com/errors/tenant_id_mismatch",
                  "title": "Tenant ID mismatch",
                  "status": 400,
                  "detail": "X-Tenant-Id does not match the tenant the credential is scoped to.",
                  "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
                  "code": "tenant_id_mismatch",
                  "retryable": false
                }
              },
              "gcpServiceRequired": {
                "summary": "GCP region filter without commitment type",
                "value": {
                  "type": "https://developer.doit.com/errors/gcp_service_required",
                  "title": "GCP service required",
                  "status": 400,
                  "detail": "The region query parameter requires gcp_service.",
                  "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
                  "code": "gcp_service_required",
                  "retryable": false
                }
              },
              "paginationTokenInvalid": {
                "summary": "Structurally invalid pagination cursor",
                "value": {
                  "type": "https://developer.doit.com/errors/pagination_token_invalid",
                  "title": "Invalid pagination token",
                  "status": 400,
                  "detail": "The pageToken cursor is structurally invalid (decode failure or tampering).",
                  "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
                  "code": "pagination_token_invalid",
                  "retryable": false
                }
              },
              "paginationTokenExpired": {
                "summary": "Expired pagination cursor",
                "value": {
                  "type": "https://developer.doit.com/errors/pagination_token_expired",
                  "title": "Expired pagination token",
                  "status": 400,
                  "detail": "The pageToken cursor is no longer valid; restart pagination from the beginning.",
                  "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
                  "code": "pagination_token_expired",
                  "retryable": false
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid credentials.",
        "headers": {
          "WWW-Authenticate": {
            "description": "Bearer challenge per RFC 6750.",
            "schema": {
              "type": "string",
              "example": "Bearer realm=\"api.doit.com\""
            }
          },
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Content-Language": {
            "$ref": "#/components/headers/ContentLanguage"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "example": {
              "type": "https://developer.doit.com/errors/unauthorized",
              "title": "Unauthorized",
              "status": 401,
              "detail": "missing or invalid bearer token",
              "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
              "code": "unauthorized",
              "retryable": false
            }
          }
        }
      },
      "Forbidden": {
        "description": "Authenticated but not authorized to perform this request.",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Content-Language": {
            "$ref": "#/components/headers/ContentLanguage"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "example": {
              "type": "https://developer.doit.com/errors/forbidden",
              "title": "Forbidden",
              "status": 403,
              "detail": "caller does not have permission to access this customer's commitments",
              "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
              "code": "forbidden",
              "retryable": false
            }
          }
        }
      },
      "NotFound": {
        "description": "The requested resource does not exist.",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Content-Language": {
            "$ref": "#/components/headers/ContentLanguage"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "example": {
              "type": "https://developer.doit.com/errors/not_found",
              "title": "Resource not found",
              "status": 404,
              "detail": "organization not found",
              "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
              "code": "not_found",
              "retryable": false
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Unexpected server error.",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Content-Language": {
            "$ref": "#/components/headers/ContentLanguage"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "example": {
              "type": "https://developer.doit.com/errors/internal_error",
              "title": "Internal server error",
              "status": 500,
              "detail": "an unexpected error occurred",
              "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
              "code": "internal_error",
              "retryable": true
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "Service temporarily unavailable; retry after the indicated delay.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer",
              "example": 30
            }
          },
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Content-Language": {
            "$ref": "#/components/headers/ContentLanguage"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "example": {
              "type": "https://developer.doit.com/errors/service_unavailable",
              "title": "Service unavailable",
              "status": 503,
              "detail": "entitlement check temporarily unavailable",
              "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
              "code": "service_unavailable",
              "retryable": true
            }
          }
        }
      }
    },
    "parameters": {
      "gcp_region": {
        "in": "query",
        "name": "region",
        "required": false,
        "description": "Filter by region scope, in `lower_snake_case` wire form (for example `us_east1`), or the\nliteral `global`. Requires `gcp_service`; a request with `region` but no `gcp_service`\nreturns `400` with code `gcp_service_required`. When both are omitted, all available\nregions for all available product lines are returned.\n\nThe value is format-validated, not checked against a closed region list: `compute` accepts\nonly `global`, `cloud_sql` accepts only concrete regions (never `global`), and a value that\nis malformed or incompatible with `gcp_service` returns `400` with code `validation_failed`.\nA well-formed, service-compatible region with no data returns `200` with an empty result.\nMatching is case-insensitive; the value is lowercased before validation.",
        "schema": {
          "$ref": "#/components/schemas/GcpRegion"
        }
      },
      "billingAccountId": {
        "in": "path",
        "name": "billingAccountId",
        "required": true,
        "description": "GCP Billing Account ID (format `XXXXXX-XXXXXX-XXXXXX`; the account that owns the CUDs) that scopes the request.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Z0-9]{6}-[A-Z0-9]{6}-[A-Z0-9]{6}$",
          "example": "01D4A2-4E3F1B-9C72A0"
        }
      },
      "tenantId": {
        "in": "header",
        "name": "X-Tenant-Id",
        "required": false,
        "description": "Customer (tenant) ID for the request. This is separate from authentication: you still pass your personal or service account API token in the `Authorization` header (`Bearer <token>`). See [Get Started](https://developer.doit.com/docs/start).\n\n**When to omit (most callers):** If your personal or service account token belongs to a single customer, omit this header. The API resolves that customer from the token.\n\n**When to send:** If your credential can access more than one customer, set `X-Tenant-Id` to the customer ID you want to act on. A service account can select an active direct or nested descendant of its home customer; the endpoint's normal permissions, entitlements, and resource-ownership checks still apply. A service-account target outside that customer subtree returns `403 Forbidden`. Prefer this header over the legacy `customerContext` query parameter, which only applies to legacy API keys and is ignored by personal and service account tokens.",
        "schema": {
          "type": "string",
          "example": "Kp2mN8qL4vR0sT1wX3yZ"
        }
      },
      "eligibleSpendGranularity": {
        "in": "query",
        "name": "granularity",
        "required": false,
        "description": "Time bucket size for eligible-spend data points on the recommendation response. If omitted, defaults to `day`. Coarser buckets return min/max/median usage; `hour` returns per-hour totals.",
        "schema": {
          "type": "string",
          "enum": [
            "hour",
            "day",
            "week",
            "month"
          ],
          "default": "day",
          "x-enumDescriptions": {
            "hour": "One point per hour (typically last 24 hours of eligible usage).",
            "day": "One point per day (typically last 21 days).",
            "week": "One point per week (typically last 16 weeks).",
            "month": "One point per month (typically last 6 months)."
          }
        }
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "name": "Authorization",
        "description": "Use the \"Bearer <API_KEY>\" format or sign in for autofill",
        "in": "header"
      },
      "tenantId": {
        "type": "apiKey",
        "name": "X-Tenant-Id",
        "description": "Customer (tenant) ID for the request. Separate from your API token: always authenticate with `Authorization: Bearer <token>` (personal or service account). See [Get Started](https://developer.doit.com/docs/start). Omit when your token is scoped to a single customer (resolved automatically). A service account can select an active direct or nested descendant of its home customer; the endpoint's normal permissions, entitlements, and resource-ownership checks still apply. A service-account target outside that customer subtree returns `403 Forbidden`. Prefer this header over the legacy `customerContext` query parameter, which only applies to legacy API keys and is ignored by personal and service account tokens.",
        "in": "header"
      }
    },
    "headers": {
      "RequestId": {
        "description": "DoiT request identifier for support and log correlation. Format `req_<ULID>`.",
        "schema": {
          "type": "string",
          "pattern": "^req_[0-9A-HJKMNP-TV-Z]{26}$",
          "example": "req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9"
        }
      },
      "ContentLanguage": {
        "description": "Language of the response body. Always `en` for this API.",
        "schema": {
          "type": "string",
          "enum": [
            "en"
          ]
        }
      }
    }
  },
  "x-samples-languages": [
    "curl",
    "go",
    "node",
    "python"
  ],
  "x-cli-config": {
    "security": "oauth2",
    "params": {
      "client_id": "cli"
    }
  }
}
```