CostGuard API V1

CostGuard enables you to identify areas within your infrastructure that are ripe for cost optimization. Finout’s CostGuard API lets you retrieve all your CostGuard Scans and their relevant recommendations. This guide offers comprehensive information on interacting with the API endpoints to retrieve scan data, access recommendations, and manage resources.

GET/Scans

Retrieves all CostGuard scan options. For more information, see CostGuard - Scans.

Prerequisite

• Generate a Client ID and Secret Key from Finout to add in Headers.

Request

https://app.finout.io/v1/cost-guard/scans

Response

Query Response

{
    "requestId": "16514d04-2702-4374-9609-23f7f952ac4a",
    "scans": [
        {
            "scanId": "5dc3714f-e9dc-4a44-9ee0-dd422405af9d",
            "scanName": "VM - Rightsizing",
            "scanMetadata": {
                "type": "rightsizing",
                "costCenter": "GCP",
            }
        },
        {
            "scanId": "2fa30166-ba7d-4428-82e6-9ca60cddab7c",
            "scanName": "Cloud SQL - Idle",
            "scanMetadata": {
                "type": "idle",
                "costCenter": "GCP",
            }
        },
        {
            "scanId": "1cb4c4b8-cd51-4eb6-bfa8-35dc24712d86",
            "scanName": "EC2 - Rightsizing",
            "scanMetadata": {
                "type": "rightsizing",
                "costCenter": "AWS",
            }
        }
    ]
}

Errors

400 - Bad Request

401 - Unauthorized

429 - Too many requests

503 - Server unavailable

504 - Gateway Timeout

Returns a JSON object with the following properties:

• request Id - The ID of this specific request.

• scanName: The names of the scan.

• scanId: The unique identifier of the scan.

• scanMetadata: Information about the scan.

  • type - The scan type.

  • costCenter - Origin of the scan’s cloud provider.

POST /Scan Recommendations

Retrieves all resources identified in a scan based on scanId, optional filters, and groupBy. For more information, see CostGuard - Scans.

Prerequisites

• Generate a Client ID and Secret Key from Finout to add in Headers.

• You must first GET the scan you want to query

• Add the scan ID to the body of the POST query. Example:

  {

  "scanId": "scan_id"

  }

Request

https://app.finout.io/v1/cost-guard/scans-recommendations

Request without Group-By

{
    "scanId": "1cb4c4b8-cd51-4eb6-bfa8-35dc24712d86",
    "filters": {
        "costCenter": "AWS",
        "key": "extracted_resource",
        "operator": "oneOf",
        "value": [“arn:aws:rds:us-east-1: 2773333:db:prod5”,
            "arn:aws:rds:us-east-1:277415555:db:prod2"
        ]
    }
}

Request with Group-By

{
    "scanId": "1cb4c4b8-cd51-4eb6-bfa8-35dc24712d86",
    "filters": {
        "costCenter": "AWS",
        "key": "extracted_resource",
        "operator": "exists",
    },
    "groupBy": {
        "costCenter": "VirtualTag",
        "key": "Team"
    }
}

Body of Request

Parameter	Type	Description
scanId	string	The ID of the scan. Example: { "scanId":"scan_id" }
filters		Optional: For Finout Megabill filters, see the Finout API language query doc. Example: "filters": { "costCenter": "AWS", "key": "parent_cloud_service", "operator": "is", "value": "AmazonAthena" },
groupBy		Optional: Group data elements together based on common attributes or values. For Finout Megabill groupBy, see the Finout API language query doc. Example: "groupBy": { "costCenter": "AWS", "key": "parent_cloud_service" }

Response

Response without Group-By

{
    "requestId": "d1b489d4-f03e-4764-8012-607fc062bb0f",
    "scanId": "f560b303-8bae-4508-95c9-e2f5c3dbd5fd",
    "scanName": "K8s - Deployment",
    "scanMetadata": {
        "type": "rightsizing",
        "costCenter": "Kubernetes"
    },
    "scanTotalCost": 86677.85059723351,
    "scanTotalWaste": 55737.14096863286,
    "scanYearlyPotentialSavings": 20344056.453550994,
    "data": [
        {
            "group": "Total",
            "groupTotalCost": 86677.85059723351,
            "groupTotalWaste": 55737.14096863286,
            "groupYearlyPotentialSavings": 20344056.453550994,
            "resources": [
                {
                    "resourceId": "aged-reload-aged-pilot",
                    "resourceTotalCost": 4679.839865741083,
                    "resourceTotalWaste": 2530.3243357423294,
                    "resourceYearlyPotentialSavings": 61571.225503063346,
                    "resourceMetadata": {
                        "analysisDays": 14,
                        "cloudOrigin": ""
                    },
                    "resourceMetrics": {
                        "maxCpuUsage": 8.01002669573929,
                        "maxCpuRequest": 8,
                        "avgCpuUsage": 1.1554730905072397,
                        "avgCpuRequest": 7.493153300600109,
                        "maxMemoryUsage": 89062.91086108514,
                        "maxMemoryRequest": 216347.6063058126,
                        "avgMemoryUsage": 68489.30242539593,
                        "avgMemoryRequest": 216347.60630581254
                    },
                    "resourceLastRunTime": 1765856257833
                },
                {
                    "resourceId": "aged-slab-hot-BLT",
                    "resourceTotalCost": 1968.593869434014,
                    "resourceTotalWaste": 1733.4266341628052,
                    "resourceYearlyPotentialSavings": 42180.04809796159,
                    "resourceMetadata": {
                        "analysisDays": 14,
                        "cloudOrigin": ""
                    },
                    "resourceMetrics": {
                        "maxCpuUsage": 7.904428521495886,
                        "maxCpuRequest": 8,
                        "avgCpuUsage": 0.9027982431412895,
                        "avgCpuRequest": 8,
                        "maxMemoryUsage": 12031.6244882169,
                        "maxMemoryRequest": 17307.808504465007,
                        "avgMemoryUsage": 5932.296807102493,
                        "avgMemoryRequest": 17307.808504465007
                    },
                    "resourceLastRunTime": 1765856257833
                },
                {
                    "resourceId": "each-salt-hot-BLT",
                    "resourceTotalCost": 1884.8946358356357,
                    "resourceTotalWaste": 1694.393482427691,
                    "resourceYearlyPotentialSavings": 41230.24140574048,
                    "resourceMetadata": {
                        "analysisDays": 14,
                        "cloudOrigin": ""
                    },
                    "resourceMetrics": {
                        "maxCpuUsage": 1.1388780771251408,
                        "maxCpuRequest": 3,
                        "avgCpuUsage": 0.952773854764212,
                        "avgCpuRequest": 3,
                        "maxMemoryUsage": 934.9129243366968,
                        "maxMemoryRequest": 1622.6070472935944,
                        "avgMemoryUsage": 932.9602143489114,
                        "avgMemoryRequest": 1622.6070472935942
                    },
                    "resourceLastRunTime": 1765856257833
                }
            ]
        }
    ]
}

Response with Group-By

{
    "requestId": "6594126f-2348-4b04-ae3f-3347c5cfa57a",
    "scanId": "f560b303-8bae-4508-95c9-e2f5c3dbd5fd",
    "scanName": "K8s - Deployment",
    "scanMetadata": {
        "type": "rightsizing",
        "costCenter": "Kubernetes"
    },
    "scanTotalCost": 316.9068523268031,
    "scanTotalWaste": 162.12339119682812,
    "scanYearlyPotentialSavings": 59175.037786842266,
    "data": [
        {
            "group": "lead-centerline",
            "groupTotalCost": 316.9068523268031,
            "groupTotalWaste": 162.12339119682812,
            "groupYearlyPotentialSavings": 59175.037786842266,
            "resources": [
                {
                    "resourceId": "aged-container-lead-centerline",
                    "resourceTotalCost": 87.9624669440481,
                    "resourceTotalWaste": 33.51589786106615,
                    "resourceYearlyPotentialSavings": 815.5535146192763,
                    "resourceMetadata": {
                        "analysisDays": 14,
                        "cloudOrigin": "amazon-cur"
                    },
                    "resourceMetrics": {
                        "maxCpuUsage": 3.9382486752918973,
                        "maxCpuRequest": 3,
                        "avgCpuUsage": 2.246313452712608,
                        "avgCpuRequest": 3,
                        "maxMemoryUsage": 202.38434507882266,
                        "maxMemoryRequest": 528.1923982075502,
                        "avgMemoryUsage": 110.26460146598022,
                        "avgMemoryRequest": 528.1923982075507
                    },
                    "resourceLastRunTime": 1765856257833
                },
                {
                    "resourceId": "drab-photon-lead-centerline",
                    "resourceTotalCost": 31.17496470148646,
                    "resourceTotalWaste": 27.563941317702223,
                    "resourceYearlyPotentialSavings": 670.7225720640874,
                    "resourceMetadata": {
                        "analysisDays": 14,
                        "cloudOrigin": "amazon-cur"
                    },
                    "resourceMetrics": {
                        "maxCpuUsage": 2.9966947894770124,
                        "maxCpuRequest": 3,
                        "avgCpuUsage": 1.0941170966345501,
                        "avgCpuRequest": 3,
                        "maxMemoryUsage": 18847.666784873785,
                        "maxMemoryRequest": 29206.926851284697,
                        "avgMemoryUsage": 3370.799120811016,
                        "avgMemoryRequest": 29206.926851284697
                    },
                    "resourceLastRunTime": 1765856257833
                },
                {
                    "resourceId": "lazy-channel-lead-centerline",
                    "resourceTotalCost": 0.6580579141684162,
                    "resourceTotalWaste": 0.4162315510915807,
                    "resourceYearlyPotentialSavings": 10.128301076561797,
                    "resourceMetadata": {
                        "analysisDays": 14,
                        "cloudOrigin": "amazon-cur"
                    },
                    "resourceMetrics": {
                        "maxCpuUsage": 0.4030787248206317,
                        "maxCpuRequest": 0.3000000000000004,
                        "avgCpuUsage": 0.013685861920672806,
                        "avgCpuRequest": 0.3000000000000003,
                        "maxMemoryUsage": 1957.798768496728,
                        "maxMemoryRequest": 3169.1543892453014,
                        "avgMemoryUsage": 1498.08739953655,
                        "avgMemoryRequest": 3169.154389245302
                    },
                    "resourceLastRunTime": 1765856257833
                }
            ]
        }
    ]
}
           

Errors

400 - Bad Request

401 - Unauthorized

429 - Too many requests

503 - Server unavailable

504 - Gateway Timeout

Returns a JSON object with the following properties:

• requestId -The ID of this specific request.

• scanName - The name of the scan.

• scanTotalCost - The sum of resources cost identified by the scan during the analysisDays.

• scanTotalWaste - Waste of the scan during the analysisDays.

• scanYearlyPotentialSavings - Yearly potential savings for the scan based on the scan's total waste.

• scanMetadata - Additional information on the scan:

  • type - Scan type: rightsizing/idle

  • costCenter - scan cloud provider origin

• data - All resources in a scan’s results

  • group - The value of the group. If there is no groupBy value, the value will be “Total”.

  • groupTotalCost - Cost of the scans during the analysisDays.

  • groupTotalWaste - Waste of the scan during analysisDays.

  • groupYearlyPotentialSavings - Yearly potential savings for the group based on the group's total waste.

  • resources - All resources in a scan’s results.

    • analysisDays - The duration in days on which the scan analysis is based (for a particular scan).

    • scanLastRunTime - The last time the scan was run (for a particular scan).

Scan Details

The details for the AWS, K8S, Datadog, and GCP scan recommendation queries.

AWS

EC2 - Idle

resourceMetadata

Field	Type	Description	Example Value
accountId	string	The account ID of the resource.	“1234”
accountName	string	The account name of the resource.	"finout"
instanceType	string	The type of the instance.	“t2.medium”
productVCPU	number	The core quantity.	“4”

resourceMetrics

Field	Type	Description	Example Value
maxEC2CpuUtilization	float	CPU Utilization percentage represents the peak CPU usage within the scan analysisDays. This value is determined by identifying the highest recorded CPU usage during the specified period, expressed as a percentage of the total CPU capacity.	“1.96721311475231”
totalEC2NetworkIn	float	The resource "NetworkIn'' represents the total amount of incoming network traffic within the scan analysis days. This value is determined by aggregating all recorded incoming network traffic data, providing a comprehensive measure of the total network usage for incoming data.	“2847257.3333333335”
totalEC2NetworkOut	float	The resource Networkout- The resource "NetworkOut" represents the total amount of outgoing network traffic within the scan analysisDays. This value is determined by compiling all outgoing network traffic data recorded and provides a comprehensive measure of the total network usage for outgoing data.	“1976763”

EC2 - Rightsizing

resourceMetadata

Field	Type	Description	Example Value
accountId	string	The account ID of the resource.	“1234”
accountName	string	Account of the resource.	"finout"
instanceType	string	The size of the instance.	“t2.medium”
productVCPU	number	The core quantity.	“4”

resourceMetrics

Field	Type	Description	Example Value
maxEC2CpuUtilization	float	The maximum CPU usage during the analysis days.	“1.235593220338884”
usedCpu	float	The maximum CPU used during the analysisDays.	“1.235593220338884”

resourceRecommendations

Field	Type	Description	Example Value
targetCpu	float	Number of vCPU of the target instance.	1
targetMemory	float	The target of the memory.	512
targetInstanceType	string	The recommended instance type.	“t2.nano”

RDS- idle

resourceMetadata

Field	Type	Description	Example Value
accountName	string	The AWS account ID.	"finout"
instanceType	string	The size of the instance.	“t2.medium”

resourceMetrics

Field	Type	Description	Example Value
maxRDSDatabaseConnections	float	The maximum daily total of connections during the scan analysisDays.	0

RDS - Rightsizing

resourceMetadata

Field	Type	Description	Example Value
accountId	string	The account ID of the resource.	“1234”
accountName	string	AWS account ID.	"finout"
instanceType	string	The size of the instance.	db.r5.xlarge”

resourceMetrics

Field	Type	Description	Example Value
usedCpu	float	The maximum CPU used during the analysisDays.	“1.235593220338884”
usedMemory	float	The mximum memory that was used during the day's analysis.	“1.235593220338884”
maxRDSCpuUtilization	float	CPU utilization percentage- represents the peak CPU usage within the scan analysisDays. This value is determined by identifying the highest recorded CPU usage during the specified period and expressed as a percentage of the total CPU capacity.	“0.2”

resourceRecommendations

Field	Type	Description	Example Value
targetInstanceCpu	float	The scan results determined that the CPU of the target machine enables maximum CPU utilization without impacting performance.	1
targetInstanceMemory	float	The memory of the target machine.	512
targetInstanceType	string	The recommended instance type is based on the CPU scan result.	“db.r5.large”

Scans: EBS-Idle, EBS- rightsizing

Metadata

Field	Type	Description	Example Value
accountId	string	The account ID of the resource.	“1234”
accountName	string	Account of the resource.	"finout"
usageType	string	The type of the EBS.	“EBS:VolumeUsage.gp2”
state	string	The state of the EBS: Available - The EBS volume is not attached to any EC2 instance and is considered idle.	“Available”

Scans: EBS - gp2

Metadata

Field	Type	Description	Value
accountId	string	The account id of the resource.	“1234”
accountName	string	Account of the resource.	"finout"
usageType	string	The type of the EBS.	“EBS:VolumeUsage.gp2”

resourceRecommendations

Field	Type	Description	Example Value
targetVolumeType	string	The target volume type for the EBS.	gp3

Scans: Application Load Balancer - Idle, Network Load Balancer - Idle, Classic Load Balancer - Idle, Gateway Load Balancer - Idle

Metadata

Field	Type	Description	Example Value
accountId	string	The account IDof the resource.	“1234”
accountName	string	The account of the resource.	"finout"
apiOperation	string	The type of the Load Balancer.	“Load Balancing”

resourceMetrics

Field	Type	Description	Example Value
totalELBRequestCount	float	Indicates the total number of HTTP or HTTPS requests received by the Elastic Load Balancer within the scan timeframe.	0

Scans: Elastic IP - Idle

Metadata

Field	Type	Description	Example Value
accountId	string	The account ID of the resource.	“1234”
accountName	string	The account of the resource.	"finout"
region	string	The region of the account.	“us-east-1”

resourceMetrics

Field	Type	Description	Example Value
totalIdleHours	float	The total hours of idle Elastic IPs during the analysis period.	722

Scans: elasticache - Idle

Metadata

Field	Type	Description	Example Value
accountId	string	The account IDof the resource.	“1234”
accountName	string	The account of the resource.	"finout"
instanceType	string	The size of the instance.	“cache.m5.large

resourceMetrics

Field	Type	Description	Example Value
maxElastiCacheCpuUtilization	float	CPU utilization percentage represents the peak CPU usage within the scan analysisDays. This value is determined by identifying the highest recorded CPU usage during the specified period and is expressed as a percentage of the total CPU capacity.	“1.21”

Scans: S3 - Idle

Metadata

Field	Type	Description	Example Value
accountId	string	The account IDof the resource.	“1234”
accountName	string	Account of the resource.	"finout"
instanceType	string	The size of the instance.	“cache.m5.large

resourceMetrics

Field	Type	Description	Example Value
s3AllRequests	float	Represents the total number of requests sent to an S3 bucket. For an idle bucket, the expected result would be 0, indicating no requests have been made.	“0”

K8S

Scans: K8s - Deployment/StatefulSet/CronJob/DaemonSet/ReplicaSet

resourceMetadata

Field	Type	Description	Example Value
cloudOrigin	string	The cloud platform where the Kubernetes resources are running.	“amazon-cur”

resourceMetrics

Field	Type	Type	Example Value
maxCpuUsage	float	Resource maximum CPU used during the analysis days.	0.064450918833
maxCpuRequest	float	Resource maximum CPU request during the analysis time frame.	1
avgCpuUsage	float	Resource average CPU used during the analysis time frame.	0.00067
avgCpuRequest	float	Resource average CPU request during the analysis time frame.	1
maxMemoryUsage	float	Resource maximum memory used during the analysis time frame.	521.361
maxMemoryRequest	float	Resource maximum meme request during the analysis time frame.	12980
avgMemoryUsage		Resource average mem used during the analysis days.	322
avgMemoryRequest		Resources average mem request during the analysis time frame.	12980

Datadog

Scans: Logs - Idle (debug)

Metadata

Field	Type	Description	Example Value
product	string	Datadog service	“Logs indexed 3day”
service	string	Datadog tag: service	“Internal service”
datadogIndex	string	Datadog tag: index	“production”
status	string	The status of the log is "debug," and is therefore considered idle.	“debug”

Scans: Custom Metrics - Idle

Metadata

Field	Type	Description	Example Value
product	string	Datadog sub service.	“Timeseries”
wasteType	string	Custom metrics that are not being used in any dashboards.	“idle”

GCP

VM - Idle

resourceMetadata

Field	Type	Description	Example Value
projectId	string	The project ID of the resource.	“1234”
projectName	string	Project of the resource.	"finout"
computeMachineSpec	string	Current machine type.	“n1-standard-4”
computeCores	number	Number of cores on the machine.	6
computeMemory	number	Amount of Memory configured to the machine (In MegaBytes).	30720

resourceMetrics

Field	Type	Description	Example Value
maxComputeCpuUtilization	float	The maximum CPU usage during the analysis days.	“1.235593220338884”
avgBytesReceived	float	Average amounts of data received daily by the resource (in bytes) during the analysis timeframe.	889167
avgBytesSent	float	Average amounts of data sent daily by the resource (in bytes) during the analysis time frame.	889167

VM - Rightsizing ​​ resourceMetadata

Field	Type	Description	Example Value
projectId	string	The project ID of the resource.	“1234”
projectName	string	Project of the resource.	"finout"
computeMachineSpec	string	Current machine type.	“n1-standard-4”
computeCores	number	Number of cores on the machine.	“6”
computeMemory	number	Amount of Memory configured to the machine (In MegaBytes).	30720

resourceMetrics

Field	Type	Description	Example Value
maxComputeCpuUtilization	float	Maximum CPU usage during the analysis days (in %).	“4.0”

resourceRecommendations

Field	Type	Description	Example Value
targetMachineSpec	String	The recommended machine type for rightsizing.	“custom-32-262144”
targetMemory	number	Target of the memory (In GigaBytes).	512
targetCpu	number	Target of the CPU.	2

Snapshot - Idle

Metadata

Field	Type	Description	Example Value
projectId	string	The project ID of the resource.	“1234”
projectName	string	The project of the resource.	"finout"

Scans: Persistent Disk - Idle

Metadata

Field	Type	Description	Example Value
projectId	string	The project ID of the resource.	“1234”
projectName	string	Project of the resource.	"finout"

SQL - Idle

resourceMetadata

Field	Type	Description	Example Value
projectId	string	The project ID of the resource.	“1234”
projectName	string	Project of the resource.	"finout"
instanceType	string	The size of the instance.	“t2.medium”

resourceMetrics

Field	Type	Description	Example Value
maxSqlCpuUtilization	float	CPU utilization percentage represents the peak CPU usage within the scan analysisDays. This value is determined by identifying the highest recorded CPU usage during the specified period, expressed as a percentage of the total CPU capacity	“1.21”
maxSqlMemoryUtilization	float	The maximum memory used during the scan analysisDays (In GigaBytes).	“4.2”

Cloud Native Scans

CostGuard surfaces cloud-native cost recommendations directly from your cloud providers, giving you immediate visibility into optimization opportunities without leaving the platform. See Cloud Native Scans for more details.