Skip to main content
All CollectionsAPI
CostGuard API
CostGuard API
Updated over a week ago

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:

  1. Select your profile from the user dropdown on the top left of any screen in Finout.

  2. Click Admin Portal.
    The Profile window appears.

  3. Select API Tokens.
    The API Token screen appears.

  4. Click Generate Token.
    The Generate Token window appears.

  5. Enter a Description, choose a role, choose token expiration, and click Create.
    Your token is generated.

  6. Copy the Client ID and the Secret Key, which won't be accessible later, and then click Done.

  7. 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

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

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:

{

"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

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”

Did this answer your question?