CostGuard API
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.
Configuring API Access
Finout API is fully secured using a secret key and client token, which can be managed from your Finout account. Your Finout account allows for five concurrent requests per API key. When you generate the API token, it creates both a secret key and a client ID (token). These parameters will be passed in the Authorization header when invoking any Finout API methods.
Important: Copy and save your Client ID and Secret Key for future use. They will only appear once and will not show again.
To configure API access:
Select your profile from the user dropdown on the top left of any screen in Finout.
Click Admin Portal.
The Profile window appears.
Select API Tokens.
The API Token screen appears.
Click Generate Token.
The Generate Token window appears.
Enter a Description, choose a role, choose token expiration, and click Create.
Your token is generated.Copy the Client ID and the Secret Key, which won't be accessible later, and then click Done.
Add the Client ID and Secret Key in Headers when invoking any of the Finout endpoints:
x-finout-client-id
x-finout-secret-key
GET Scans
Description
Retrieves all CostGuard scan options. For more information, see CostGuard - Scans.
Prerequisites
Generate a Client ID and Secret Key from Finout to add in Headers.
Base URL
The base URL for all API requests is: https://app.finout.io/v1/
Endpoints
GET/cost-guard/scans
Parameters
None
Response
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.
scanLastRunTime: The last time the scan was run.
scanMetadata: Information about the scan.
type - The scan type.
costCenter - Origin of the scan’s cloud provider.
analysisDays - The number of days on which the scan analysis is based.
Example
Request:
https://app.finout.io/v1/cost-guard/scans
Response:
{
"requestId": "3f177652-04cd-4231-84f2-0aa4fadda061",
"scans": [
{
"scanId": "cbfaeb2c-7b77-48a3-b173-a88d40875e17",
"scanName": "EC2 - Idle",
"scanLastRunTime": 1704153600000,
"scanMetadata": {
"type": "idle",
"costCenter": "AWS",
"analysisDays": 7
}
},
{
"scanId": "1cb4c4b8-cd51-4eb6-bfa8-35dc24712d86",
"scanName": "EC2 - Rightsizing",
"scanLastRunTime": 1712448000000,
"scanMetadata": {
"type": "rightsizing",
"costCenter": "AWS",
"analysisDays": 3
}
},
{
"scanId": "f560b303-8bae-4508-95c9-e2f5c3dbd5fd",
"scanName": "K8s - Deployment",
"scanLastRunTime": 1721806550318,
"scanMetadata": {
"type": "rightsizing",
"costCenter": "Kubernetes",
"analysisDays": 14
}
},
{
"scanId": "aac0289e-053e-43b0-b22d-3e1e638a6ea8",
"scanName": "Logs - Idle (debug)",
"scanLastRunTime": 1721806550318,
"scanMetadata": {
"type": "idle",
"costCenter": "Datadog",
"analysisDays": 7
}
}
]
}
Errors
400 | Bad Request |
401 | Unauthorized |
429 | Too many requests |
503 | Server unavailable |
504 | Gateway Timeout |
POST Scan Recommendations
Description
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"
}
Base URL
The base URL for all API requests is: https://app.finout.io/v1/
Endpoints
POST/cost-guard/scans-recommendations
Parameters
Parameter | Type | Description |
scanId | string | The ID of the scan. Example:
|
filters |
| Optional: For Finout Megabill filters, see the Finout API language query doc. Example:
|
groupBy |
| Optional: Group data elements together based on common attributes or values. For Finout Megabill groupBy, see the Finout API language query doc. Example:
|
Response
Returns a JSON object with the following properties:
requestId -The ID of this specific request.
scanName - The name of the scan.
scanLastRunTime - The last time the scan was run.
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
analysisDays - The duration in days on which the scan analysis is based
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.
Example
Request:
https://app.finout.io/v1/cost-guard/scans-recommendations
Request without ‘groupBy’:
{
"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 ‘groupBy’:
{
"scanId": "1cb4c4b8-cd51-4eb6-bfa8-35dc24712d86",
"filters": {
"costCenter": "AWS",
"key": "extracted_resource",
"operator": "exists",
},
"groupBy": {
"costCenter": "VirtualTag",
"key": "Team"
}
}
Response:
Response without a ‘group by’:
{
“requestId”: “03aa9146-dfc9-4eb6-ade2-3e134adc8310”,
"scanId": "1cb4c4b8-cd51-4eb6-bfa8-35dc24712d86",
"scanName": "EC2 - Rightsizing",
"scanLastRunTime": 1717804800000,
"scanTotalCost": 40,
"scanTotalWaste": 5.5,
"scanYearlyPotentialSavings": 200,
"scanMetadata": {
"type": "rightsizing",
"costCenter": "AWS",
"analysisDays": 7
},
"data": [
{
"group": "total",
"groupTotalCost": 40,
"groupTotalWaste": 5.5,
"scanYearlyPotentialSavings": 200,
"resources": [
{
"resourceId": "arn:aws:rds:us-east-1:2773333:db:prod5",
"resourceMetadata": {
"accountName": "Finout",
"instanceType": "t2.medium"
},
"resourceTotalWaste": 0.9437789124697027,
"resourceTotalCost": 1.0489,
"resourceYearlyPotentialSavings": 20,
"resourceMetrics": {
"usedCpu": 1.235593220338884
},
"resourceRecommendation": {
"targetCpu": 1.0,
"targetMemory": 512,
"targetInstanceType": "t2.nano"
}
},
{
"resourceId": "arn:aws:rds:us-east-1:277415555:db:prod2",
"resourceMetadata": {
"accountName": "Finout",
"instanceType": "t2.medium"
},
"resourceTotalWaste": 0.9437789124697027,
"resourceTotalCost": 1.0489,
"resourceYearlyPotentialSavings": 40,
"resourceMetrics": {
"usedCpu": 1.235593220338884
},
"recommendation": {
"targetCpu": 1.0,
"targetMemory": 512,
"targetInstanceType": "t2.nano"
}
}
]
}
]
}
Response with a ‘group by’:
{
“requestId”: “03aa9146-dfc9-4eb6-ade2-3e134adc8310”,
"scanId": "1cb4c4b8-cd51-4eb6-bfa8-35dc24712d86",
"scanName": "EC2 - Rightsizing",
"scanLastRunTime": 1717804800000,
"scanTotalCost": 40,
"scanTotalWaste": 5.5,
"scanYearlyPotentialSavings": 200,
"scanMetadata": {
"type": "rightsizing",
"costCenter": "AWS",
"analysisDays": 7
},
"data": [
{
"group": "TeamA",
"groupTotalCost": 10,
"groupTotalWaste": 2.5,
"groupYearlyPotentialSavings": 300,
"resources": [
{
"resourceId": "arn:aws:rds:us-east-1:2774443567:db:prod5",
"resourceMetadata": {
"accountName": "Finout",
"instanceType": "t2.medium"
},
"resourceTotalWaste": 0.9437789124697027,
"resourceTotalCost": 1.0489,
"resourceYearlyPotentialSavings": 200,
"resourceMetrics": {
"usedCpu": 1.235593220338884
},
"resourceRecommendations": {
"targetCpu": 1.0,
"targetMemory": 512,
"targetInstanceType": "t2.nano"
}
},
{
"resourceId": "arn:aws:rds:us-east-1:27741144443:db:prod2",
"resourceMetadata": {
"accountName": "Finout",
"instanceType": "t2.medium"
},
"resourceTotalWaste": 0.9437789124697027,
"resourceTotalCost": 1.0489,
"resourceYearlyPotentialSavings": 140,
"resourceMetrics": {
"usedCpu": 1.235593220338884
},
"resourceRecommendations": {
"targetCpu": 1.0,
"targetMemory": 512,
"targetInstanceType": "t2.nano"
}
}
]
},
{
"group": "TeamB",
"groupTotalCost": 7,
"groupTotalWaste": 1.5,
"groupYearlyPotentialSavings": 100,
"resources": [
{
"resourceId": "arn:aws:rds:us-east-1:2774111111:db:dev1",
"resourceMetadata": {
"accountName": "Finout",
"instanceType": "t2.medium"
},
"resourceTotalWaste": 0.9437789124697027,
"resourceTotalCost": 1.0489,
"resourceYearlyPotentialSavings": 400,
"resourceMetrics": {
"usedCpu": 1.235593220338884
},
"resourceRecommendations": {
"targetCpu": 1.0,
"targetMemory": 512,
"targetInstanceType": "t2.nano"
}
},
{
"resourceId": "arn:aws:rds:us-east-1:27741122222:db:prod",
"resourceMetadata": {
"accountName": "Finout",
"instanceType": "t2.medium"
},
"resourceTotalWaste": 0.9437789124697027,
"resourceTotalCost": 1.0489,
"resourceYearlyPotentialSavings": 250,
"resourceMetrics": {
"usedCpu": 1.235593220338884
}
}
]
}
]
}
Errors
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
422 | Unprocessable request |
429 | Too many requests |
500 | Internal Server Error |
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 | 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” |
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 | Description | 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” |