All pages
Powered by GitBook
2 of 9

Finout API

The Finout API provides seamless access to powerful cloud cost management tools, enabling you to integrate, analyze, and optimize your cloud expenses. With endpoints for cost insights, tagging, forecasting, and more, the API empowers teams to automate workflows, track spending, and drive efficiency across their cloud environments.

The following APIs are available:

Generate an API Token

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

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

Filter Object Definition

In the Finout Virtual Tags API documentation, the structure of the filters object can be explained by starting with simpler usage and then detailing more complex scenarios:

  1. Simple Conditions Without Logical Operators:

    • Use direct condition keys for single-condition requirements.

      Example JSON:

      {
  "to": "Asaf",
  "filters": {
    "costCenter": "AWS",
    "key": "aws_account_name",
    "displayName": "Account Name",
    "operator": "oneOf",
    "value": [
      "004a533177",
      "0371d7d3bf"
    ]
  }

  2. Complex Conditions with Nested Logical Operators:

    • AND and OR keys represent logical operators for grouping multiple conditions.

    • You can nest multiple layers of AND and OR for intricate conditional logic.

      Example JSON:

      {
  "filters": {
    "AND": [
      {
        "OR": [
          {
            "costCenter": "AWS",
            "key": "condition1",
            "operator": "equals",
            "value": "value1"
          },
          {
            "costCenter": "AWS",
            "key": "condition2",
            "operator": "equals",
            "value": "value2"
          }
        ]
      },
      {
        "costCenter": "AWS",
        "key": "condition3",
        "operator": "equals",
        "value": "value3"
      }
    ]
  }
}

Filter operator object definition

Field
Type
Description
Example Value

costCenter

string

The cost center associated with the filter.

"AWS" , "GCP", "Kubernetes" , "Snowflake" , "Virtual Tags" , "Datadog" , "Azure" , "Custom Cost"

operator

string

The comparison operator to apply for the filter (e.g., "oneOf", "equal", "greaterThan").

"oneOf"

value

array

An array of values to use the operator against.

["Amazon Web Services EMEA KFIR"]

key

string

The key in Finout filters.

For non-unique keys or specific keys (finrichment), a transform function is applied as follows:

finrichment is returned as f_

plus the Kubernetes key and the node/pod label is returned as nl_<key>/pl_<key>

“1233442423423”

“finrichment_usage_type” -> “f_usage_type”

Use Finout’s Query Language API to get a list of the available keys.

Note: "displayName" is retrieved in the GET API call. This parameter should not be sent in the POST/PUT API calls.

Supported Operators

The following operators can be used in the rule definitions to specify filtering conditions:

  • oneOf: Matches the resource value if it is equal to any of the specified values.

  • notOneOf: Matches the resource value if it is not equal to any of the specified values.

  • is: Matches the resource value if it is exactly equal to the specified value.

  • isNot: Matches the resource value if it is not equal to the specified value.

  • contains: Matches the resource value if it contains the specified substring.

  • notContains: Matches the resource value if it does not contain the specified substring.

  • exists: Matches the resource value if it exists (not null or empty).

  • notExists: Matches the resource value if it does not exist (null or empty).

Example rule configuration

{
"requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Test",
"rules": [
{
"to": "Finout",
"filters": {
"AND": [
{
"costCenter": "AWS",
"key": "aws_account_name",
"displayName": "Account Name",
"operator": "oneOf",
"value": [
"Finout"
]
},
{
"costCenter": "AWS",
"key": "f_operation",
"displayName": "API Operation",
"operator": "oneOf",
"value": [
"AAAA"
]
},
{
"costCenter": "Virtual Tags",
"key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"displayName": "Cost per Customer",
"operator": "oneOf",
"value": [
"Abra"
]
}
]
}
},
{
"to": "Finout-Subaccount",
"filters": {
"costCenter": "AWS",
"key": "aws_account_name",
"displayName": "Account Name",
"operator": "oneOf",
"value": [
"Finout-Subaccount"
]
}
},
{
"to": "AWS",
"filters": {
"costCenter": "Global",
"key": "cost_center_type",
"displayName": "Cost Center",
"operator": "oneOf",
"value": [
"AWS"
]
}
}
],
"category": "Project",
"createdBy": "User",
"updatedBy": "User",
"createdAt": "Wed Mar 13 2024 15:40:46 GMT+0000 (Greenwich Mean Time)",
"updatedAt": "Thu Mar 21 2024 10:49:17 GMT+0000 (Greenwich Mean Time)",
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"defaultValue": "Untagged"

In the example above, the rule engine is configured with two rules. The first rule filters resources with costCenter equal to "virtualTag" and type equal to "virtual_tag" using the oneOf operator, matching the values "Aged", "AllArid", "BidBare", "Calm", or "Coal". The matching resources are then directed to the "Application" destination.

The second rule filters resources with costCenter equal to "virtualTag" and type equal to "virtual_tag" using the contains operator, matching the value "Jet". The matching resources are directed to the "Backend" destination.

Example rules and filter conditions

{
  "requestId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "accountId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "exampleName",
  "rules": [
    {
      "to": "Tag1",
      "filters": {
        "AND": [
          {
            "OR": [
              {
                "costCenter": "Center1",
                "key": "service_key",
                "displayName": "Service Name",
                "operator": "oneOf",
                "value": [
                  "ServiceA",
                  "ServiceB",
                  "ServiceC"
                ]
              },
              {
                "costCenter": "Center1",
                "key": "account_name_key",
                "displayName": "Account Name",
                "operator": "oneOf",
                "value": [
                  "AccountX",
                  "AccountY"
                ]
              }
            ]
          },
          {
            "costCenter": "Center1",
            "key": "service_key",
            "displayName": "Service Name",
            "operator": "oneOf",
            "value": [
              "ServiceA",
              "ServiceB"
            ]
          }
        ]
      }
    },
    {
      "to": "Tag2",
      "filters": {
        "costCenter": "Center2",
        "key": "account_name_key",
        "displayName": "Account Name",
        "operator": "oneOf",
        "value": [
          "AccountZ",
          "AccountW"
        ]
      }
    }
  ],
  "createdBy": "CreatorName",
  "updatedBy": "UpdaterName",
  "createdAt": "Date and Time",
  "updatedAt": "Date and Time",
  "id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "defaultValue": "DefaultTag"
}

In the provided example, the third rule illustrates complex conditional logic using both "AND" and "OR" operators. This rule's filter conditions demonstrate the logic: "(condition 1 AND condition 2) OR (condition 1 AND condition 3)". This showcases how multiple conditions can be intricately grouped within "AND" or "OR" relationships, allowing for the creation of sophisticated filtering logic for virtual tags. This example serves to show the versatility and depth of the filtering system in handling diverse and complex tagging scenarios.

Cost API

Finout Cost API enables you to query and analyze costs using user-defined Finout Views. You can easily get a list of your views and retrieve the costs for a specified view. You can query the costs for any date range of up to 90 days specified in UTC timestamps. The results are returned in JSON format for easy processing.

Note: Only cost data is returned when querying a view via the Cost API.

GET/Views

Description

Gets a list of all your account views. For more information on views, see Finout Views.

Prerequisites

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

  • You must create a view in the MegaBill before querying the GET view. There is currently no 'Create View' API option.

Request https://app.finout.io/v1/view

Response

{
    "data": [
        {
            "name": "Cost Ratio - Weightings by Group Name",
            "id": "25568bb9-7d9b-4b72-9361-07abcb4e5f29"
        },
        {
            "name": "Shared Services - Support, Marketplace, Security",
            "id": "08252cda-3f70-4779-822c-cf4bdf65cc28"
        },

        {
            "name": "K8s by App_Component",
            "id": "f76be053-1138-431f-a6e1-9f6d1852398b"
        }
    ],
    "requestId": "05ac7c0f-2e85-4af0-8ef7-3ace11e420d7"
}

400

Bad Request

401

Unauthorized

429

Too many requests

503

Server unavailable

504

Gateway Timeout

sdvs

// Some code

Returns a JSON object with the following properties:

  • name: The names of your account's views.

  • id: The unique identifier of your account's views.

POST /Query by view

Description

Return all costs for a specified view and date range for up to 90 days. For more information on views, see Finout Views.

Prerequisites

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

  • You must first GET the view you want to query

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

    ​{
"viewId": "6244e453-e8b8-4f1f-9a96-4ba1ae5d48f7"
}

  • You must either specify dates or delete them completely. The query won't work when blank dates are still present. Example:

    ​​{
     "viewId": "6244e453-e8b8-4f1f-9a96-4ba1ae5d48f7",
     "date": {
         "unixTimeMillSecondsStart": 1719824738,
         "unixTimeMillSecondsEnd": 1719911138
     },
     "costType": "netAmortizedCost"
   }

Request

https://app.finout.io/v1/cost/query-by-view

{
    "viewId": "9c0344f2-94d6-4b9a-b1d5-e57353c117ee",
    "date": {
        "unixTimeMillSecondsStart": 1719824738,
        "unixTimeMillSecondsEnd": 1719911138
    },
    "costType": "netAmortizedCost"
}

Body of Request

Parameter
Type
Description

viewId

string

The ID of the view that the user queries

date

object

“unixTimeMillSecondsStart” and “unixTimeMillSecondsEnd” keys

unixTimeMillSecondsStart

Numeric

Start Date represented in Unix Epoch time

unixTimeMillSecondsEnd

Numeric

End Date represented in Unix Epoch time

costType

String

Types of costs: - blendedCost - unblendedCost - netUnblendedCost - amortizedCost - netAmortizedCost See Cost and Usage Types for an explanation of each cost.

Response 

{
    "data": [
        {
            "name": "Total",
            "data": [
                {
                    "time": 1641600000,
                    "cost": 0
                }
            ]
        }
    ],
    "request": {
        "viewId": "9c0344f2-94d6-4b9a-b1d5-e57353c117ee",
        "date": {
            "unixTimeMillSecondsStart": 1719824738,
            "unixTimeMillSecondsEnd": 1719911138
        },
        "costType": "netAmortizedCost"
    },
    "requestId": "629f36f0-191b-4c36-b8dd-13fd8ad7f37d"
}
{
  "data": [
    {
      "name": "Total",
      "data": [
        {
          "time": 1716768000000,
          "cost": 150
        },
        {
          "time": 1719100800000,
          "cost": 220
        }
      ]
    },
    {
      "name": "AmazonS3",
      "data": [
        {
          "time": 1716768000000,
          "cost": 50
        },
        {
          "time": 1719100800000,
          "cost": 20
        }
      ]
    },
    {
      "name": "AmazonEC2",
      "data": [
        {
          "time": 1716768000000,
          "cost": 100
        },
        {
          "time": 1719100800000,
          "cost"
        },
        {
          "time": 1719878400000,
          "cost": 0.04230358709842744
        }
            ]
        }
    ],
    "request": {
        "viewId": "b17c9716-31dc-4520-adf8-6d9cd7c00776",
        "date": {
            "unixTimeMillSecondsStart": 1719824738000,
            "unixTimeMillSecondsEnd": 1719911138000
        },
        "costType": "netAmortizedCost"
    },
    "requestId": "9a7a3d42-8215-43f1-8c6b-b66198ef4013"
}

400

Bad Request

401

Unauthorized

429

Too many requests

503

Server unavailable

504

Gateway Timeout

Query Language API

The MegaBill filter API allows users to query and retrieve metadata for building filters on a huge dataset. This API provides endpoints to fetch MegaBill keys, values, virtual tags, and specific metadata for individual keys. This API is used to understand the different building blocks of Finout’s MegaFilter, and the information needed to build Virtual Tags and views.

GET/Keys

Retrieves all MegaBill keys.

Prerequisites

Request https://app.finout.io/v1/megabill/query-language/keys

Response

{

    "keys": [
        {
            "costCenter": "Kubernetes",
            "key": "deployment",
            "displayName": "deployment"
        },
        {
            "costCenter": "AWS",
            "key": "f_usage_type",
            "displayName": "Usage Type"
        },
        {
            "costCenter": "databricks",
            "key": "run_name",
            "displayName": "run_name"
        },
      
        {
            "costCenter": "Custom Cost",
            "key": "customCost_QmFtYmEbabababoi",
            "displayName": "Bamba"
        }
    ],
    "requestId": "d4e8c06b-9fd3-4a80-87bd-d13878fa9bd9",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259"
}

Returns a JSON object with the following properties:

Name
Type
Description

keys

array

An array of key metadata objects.

requestId

number

The ID of the request in the Finout system.

accountId

number

The ID of the account that made the request.

The key_metadata array has the following fields:

Field
Type
Description
Examples

costCenter

string

The cost center associated with the key (display name).

"databricks"

key

string

The unique identifier in Finout.

"a3ViZXJuZXRlczpsYWJlbF9zcGFya19zcGFya19leGVjX2lk"

displayName

string

The external name identifier in Finout, is only used in Finout’s app.

"job-id"

GET/KeyValues

Retrieve all values associated with a specific key. A successful response allows you to construct a virtual tag condition based on the key values and operators.

Prerequisites

Request http://app.finout.io/v1/megabill/query-language/values/{costcenter}/{key}

Path Parameters

Name
Type
Description

cost_center

string

The ID of the cost center.

key

string

The ID of the key.

Response

{
    "values": [
        "us-east-1",
        "global",
        "eu-central-1",
        "eu-west-2",
        "ap-southeast-2",
        "ca-central-1",
        "ap-northeast-1",
        "eu-west-1",
        "us-east-2",
        "ap-northeast-2",
        "sa-east-1",
        "us-west-2",
        "us-west-1",
        "ap-south-1",
        "eu-west-3",
        "ap-southeast-1",
        "eu-north-1",
        "ap-northeast-3",
        "me-south-1",
        "af-south-1"
    ],
    "request": {
        "costCenter": "AWS",
        "key": "Region"
    },
    "requestId": "2e473bda-b96e-40a6-929c-2f5c445bf393",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259"
}

Virtual Tags API

The Virtual Tags API allows you to create, retrieve, update, and delete Virtual Tag configurations. Virtual Tags organize and categorize data based on custom rules and filters.

Note: The Reallocation and MegaBill Key segmentation are currently unsupported in the Virtual Tag API.

GET/Virtual Tags

Retrieves all virtual tag configurations.

Prerequisites

Request https://app.finout.io/v1/virtual-tags

Response

{
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "requestId": "6e0f327e-9948-440b-b577-d0203aa374e9",
    "virtualTags": [
        {
            "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
            "createdBy": "elisha.saidoff@finout.io",
            "name": "Demo Feature cost",
            "rules": [
                {
                    "to": "demo",
                    "filters": {
                        "costCenter": "AWS",
                        "key": "f_inst_type",
                        "displayName": "Instance Type",
                        "operator": "is",
                        "value": [
                            "a1.2xlarge",
                            "a1.large",
                            "a1.medium"
                        ]
                    }
                }
            ],
            "createdAt": "Sun Sep 29 2024 08:20:37 GMT+0000 (Greenwich Mean Time)",
            "updatedAt": "Tue Oct 29 2024 12:13:50 GMT+0000 (Greenwich Mean Time)",
            "updatedBy": "elisha.saidoff@finout.io",
            "id": "d8026cec-6d3b-4c54-87f7-6ea815aa3b89",
            "defaultValue": "Untagged"
        },
        {
            "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
            "name": "Org/Department",
            "rules": [
                {
                    "to": "TLV",
                    "filters": {
                        "costCenter": "Virtual Tags",
                        "key": "cc7e8b30-b141-496b-82b5-ddd4d535c79d",
                        "displayName": "Group Names",
                        "operator": "oneOf",
                        "value": [
                            "Data",
                            "Core"
                        ]
                    }
                },
                {
                    "to": "NYC",
                    "filters": {
                        "costCenter": "Virtual Tags",
                        "key": "cc7e8b30-b141-496b-82b5-ddd4d535c79d",
                        "displayName": "Group Names",
                        "operator": "oneOf",
                        "value": [
                            "Legacy",
                            "Infra",
                            "Front End"
                        ]
                    }
                }
            ],
            "createdBy": "Maks Kogan",
            "updatedBy": "maksim.kogan@finout.io",
            "createdAt": "Tue Oct 17 2023 18:08:17 GMT+0000 (Greenwich Mean Time)",
            "updatedAt": "Fri Aug 16 2024 18:00:49 GMT+0000 (Greenwich Mean Time)",
            "id": "4f816fc1-6b3a-4902-b6b5-9759ba5ca83c",
            "defaultValue": "Untagged"
        }
    ]
}

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404- Not Found

429 - Too Many Request

500 - Internal Server Error

Unprocessable Request

POST /Virtual Tag

Create a new virtual tag.

Prerequisites

Request

https://app.finout.io/v1/virtual-tags

{
  "name": "Demo Feature cost2222",
  "rules": [
    {
      "to": "Fea",
      "filters": {
        "costCenter": "AWS",
        "key": "f_inst_type",
        "displayName": "Instance Type",
        "operator": "is",
        "value": [
          "a1.2xlarge",
          "a1.large",
          "a1.medium"
        ]
      }
    }
  ],
  "defaultValue": "Untagged"
}

Body parameters

Parameter
Type
Description

name

string

The name of the virtual tag.

rules

array

An array of rules defines the filters and conditions for the virtual tag. See Virtual Tag Objects.

defaultValue

string

The defaultValue object.

Response

{
    "requestId": "5f8ae41e-02fb-4a03-900e-7451dc3d073f",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "createdBy": "Finout",
    "name": "Demo Feature cost2223",
    "archiverIgnore": false,
    "rules": [
        {
            "to": "Fea",
            "filters": {
                "costCenter": "AWS",
                "key": "f_inst_type",
                "displayName": "Instance Type",
                "operator": "is",
                "value": [
                    "a1.2xlarge",
                    "a1.large",
                    "a1.medium"
                ]
            }
        }
    ],
    "endpoints": [],
    "allocations": [],
    "createdAt": "Sun Nov 17 2024 11:55:11 GMT+0000 (Greenwich Mean Time)",
    "updatedAt": "Sun Nov 17 2024 11:55:11 GMT+0000 (Greenwich Mean Time)",
    "id": "d1a99df2-dfb3-4da6-8877-91a655d5deb8",
    "defaultValue": "Untagged"
}

PUT/Virtual Tags

Update a current virtual tag.

Prerequisites

Request

https://app.finout.io/v1/virtual-tags/{id}

Path parameter

Parameter
Type
Description

ID

String

The ID of the Virtual Tag is to be updated.

{
  "name": "Demo Feature cost2223",
  "rules": [
    {
      "to": "Fea",
      "filters": {
        "costCenter": "AWS",
        "key": "f_inst_type",
        "displayName": "Instance Type",
        "operator": "is",
        "value": [
          "NEW1",
          "NEW2",
          "NEW3"
        ]
      }
    }
  ],
  "defaultValue": "Untagged"
}

Request Body Parameters

Parameter
Type
Description

name

string

The name of the Virtual Tag.

rules

array

An array of rules defines the filters and conditions for the virtual tag. See Virtual Tag Objects.

defaultValue

string

The defaultValue object.

Response

{
    "requestId": "c17dc36d-6007-48f6-a06f-35ccb74f58a8",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "createdBy": "Finout",
    "name": "Demo Feature cost2223",
    "archiverIgnore": false,
    "rules": [
        {
            "to": "Fea",
            "filters": {
                "costCenter": "AWS",
                "key": "f_inst_type",
                "displayName": "Instance Type",
                "operator": "is",
                "value": [
                    "NEW1",
                    "NEW2",
                    "NEW3"
                ]
            }
        }
    ],
    "endpoints": [],
    "allocations": [],
    "createdAt": "Sun Nov 17 2024 11:55:11 GMT+0000 (Greenwich Mean Time)",
    "updatedAt": "Mon Nov 18 2024 08:33:52 GMT+0000 (Greenwich Mean Time)",
    "updatedBy": "Finout",
    "id": "d1a99df2-dfb3-4da6-8877-91a655d5deb8",
    "defaultValue": "Untagged"
}

GET/Virtual Tag By ID

Retrieves the specified Virtual Tag configuration.

Prerequisites

Request

https://app.finout.io/v1/virtual-tags/{id}

Path Parameter

Parameter
Type
Description

id

String

The id of the Virtual Tag to retrieve.

Response

{
    "requestId": "168b62f4-92f7-4871-aaf9-04ce725fc303",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "createdBy": "elisha.saidoff@finout.io",
    "name": "Demo Feature cost",
    "rules": [
        {
            "to": "demo",
            "filters": {
                "costCenter": "AWS",
                "key": "f_inst_type",
                "displayName": "Instance Type",
                "operator": "is",
                "value": [
                    "a1.2xlarge",
                    "a1.large",
                    "a1.medium"
                ]
            }
        }
    ],
    "createdAt": "Sun Sep 29 2024 08:20:37 GMT+0000 (Greenwich Mean Time)",
    "updatedAt": "Tue Oct 29 2024 12:13:50 GMT+0000 (Greenwich Mean Time)",
    "updatedBy": "elisha.saidoff@finout.io",
    "id": "d8026cec-6d3b-4c54-87f7-6ea815aa3b89",
    "defaultValue": "Untagged"
}

DELETE/Virtual Tag

Deletes the specified Virtual Tag.

Prerequisites

Request

https://app.finout.io/v1/virtual-tags/{id}

Path parameter

Parameter
Type
Description

id

string

The id of the Virtual Tag to delete.

Response

The Virtual tag is deleted.

Virtual Tags Objects

The Virtual Tags object represents a configuration used for resource allocation and filtering. It contains the following fields:

Field
Type
Description
Example Value

accountId

string

The unique identifier of the account is associated with the Virtual Tag.

"e12498cc-594a-4740-94a5-8324e7399bb2"

name

string

The name of the Virtual Tag.

"nir test"

rules

array

An array of RULE objects that defines the filtering criteria for the Virtual Tag.

See Filter Object Definition for more information.

createdBy

string

The name of the user who created the Virtual Tag.

"Nir"

updatedBy

string

The name of the user who last updated the Virtual Tag.

"Asaf Liveanu"

defaultValue

string

An object defining the default value for the Virtual Tag.

“untagged”

createdAt

string

The date and time when the Virtual Tag was created.

"Tue May 16 2023 13:15:53 GMT+0000 (Greenwich Mean Time)"

updatedAt

string

The date and time when the Virtual Tag was last updated.

"Sat Jun 10 2023 16:06:25 GMT+0000 (Greenwich Mean Time)"

id

string

The unique identifier of the Virtual Tag.

"b11c9be2-b7a0-4209-a00e-44ac2ccce0f7"

“Rules” object definition

Field

Type

Description

Example Value

to

string

The destination or target for the filtered data.

"Data Team"

filters

object

An object containing the filter conditions for the rule.

See Filter Object Definition for more information.

Error Handling

The API returns standard HTTP error codes to indicate the success or failure of a request. The following common HTTP errors may be returned:

  • 400 Bad Request: The request is malformed or missing the required parameters. Check the request structure carefully for syntax typos and resubmit the request.

  • 401 Unauthorized: The request lacks valid authentication credentials. Ensure that you have added your credentials to the request header and resubmit your request. If this still doesn't work, contact Finout Support.

  • 403 Forbidden: The request is understood, but the server refuses to fulfill it due to access restrictions. Contact Finout Support.

  • 404 Not Found: The requested resource is not found. Resubmit the request with a valid resource ID.

  • 429 Too Many Requests: The user has sent too many requests in a given period.

  • 422 Unprocessable Request: Check the virtual tag composition and structures.

  • 500 Internal Server Error: An unexpected error occurred on the server.

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.

GET/Scans

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

Prerequisite

Request

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

Response

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

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.

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

POST /Scan Recommendations

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

Prerequisites

Request

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

{
    "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"
        ]
    }
}
{
    "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

{

  “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"
                    }
                }
            ]
        }
    ]
}
{

  “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
                    }
                }
            ]
        }
    ]
}
```

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.

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

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”

Endpoint API

Finout’s Endpoint API provides functionalities to query existing endpoints and create new ones effortlessly. You can retrieve a list of current endpoints or create new ones, with all results returned in JSON format for seamless integration and processing.

GET/Endpoints

Gets a list of all your account endpoints.

Prerequisites

Request https://app.finout.io/v1/endpoints

Response

{ 
"endpoints": [
          {
            "type": "email",
            "name": "example@finout.io",
            "configuration": {
                "to": "example@finout.io"
            },
            "createdBy": "example",
            "createdAt": "Thu Dec 28 2023 14:09:57 GMT+0000 (Greenwich Mean Time)",
            "id": "7fecf9fb-4f36-4931-8d02-9cc53bb26af3"
        },
        {
            "type": "slack",
            "name": "Demo-Finout",
            "configuration": {
                "to": "https://hooks.slack.com/services/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"
            },
            "createdBy": "Demo-Finout",
            "createdAt": "Sun Feb 26 2023 14:33:35 GMT+0000 (Greenwich Mean Time)",
            "id": "4f806937-6f5b-478e-a81a-f4b2ece14bb1"
        },
        {
            "type": "msteams",
            "name": "BI Group/DevTeam",
            "createdBy": "Finout",
            "createdAt": "Wed Nov 13 2024 17:44:50 GMT+0000 (Greenwich Mean Time)",
            "id": "a4a41dfc-23b3-4d9d-8f17-6e45cc34e8f8"
        },
   ],
    "requestId": "3b4c8ee0-9d97-4042-8265-ce837a87469d"
}

Bad Request

Unauthorized

Too many requests

Server unavailable

Gateway Timeout

Returns a JSON object with the following properties:

  • type: The endpoint type - email or Slack.

  • name: The name of the endpoint.

  • configuration: The Slack or email URL that is configured for the endpoint.

  • to: The destination address or endpoint for the notification.

  • createdBy: The creator of the endpoint.

  • createdAt: The time and date the endpoint was created.

  • id: The unique identifier of your account's views.

  • requestId: The ID of this specific request.

POST /Endpoints

Creates an email or Slack endpoint in Finout.

Prerequisites

Request

https://app.finout.io/v1/endpoints

{
    "type": "email",
    "name": "demo",
    "configuration": {
        "to": "demo@finout.io"
    }
}

Body of Request

Parameter
Type
Description

type

string

Email or Slack

name

string

The name of the endpoint.

configuration

Object

The address where notifications or messages are sent. ​to: The destination address or endpoint for the notification.

Note: For MS Teams - All public channels in a Team will automatically mapped to an endpoint ID in Finout.

Response

{
    "endpoint": {
        "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
        "createdBy": "demo@finout.io",
        "type": "email",
        "name": "demo",
        "configuration": {
            "to": "demo@finout.io"
        },
        "createdAt": "Tue Oct 29 2024 12:11:10 GMT+0000 (Greenwich Mean Time)",
        "updatedAt": "Tue Oct 29 2024 12:11:10 GMT+0000 (Greenwich Mean Time)",
        "id": "727e16d6-affe-43bd-924a-c896197640bb"
    },
    "requestId": "0e2516ba-87fb-4210-be7e-6890fcb55adc"
}

Bad Request

Unauthorized

Too many requests

Server unavailable

Gateway Timeout

Returns a JSON object with the following properties:

  • accountId: The account id of the endpoint.

  • createdby: The creator of the endpoint.

  • type: the endpoint type - email or Slack.

  • name: The name of the endpoint.

  • configuration: What the endpoint was configured to.

  • to: The destination address or endpoint for the notification.

  • createdAt: The time and date the endpoint was created.

  • updatedAt: The time and date the endpoint was updated.

  • id: The unique identifier of your account's views.

  • requestId: The ID of this specific request.

Virtual Tag Metadata API

The Finout Metadata API allows you to query, analyze, and manage metadata associated with virtual tag values. It provides functionalities to retrieve existing metadata lists and add metadata for specific virtual tags. Results are returned in JSON format, facilitating seamless data processing and integration.

GET/Virtual Tag Metadata

Returns a list of virtual tag values and their corresponding Metadata

Prerequisites

Request

https://app.finout.io/v1/virtual-tags/virtualtagid/metadata

Response

{
    "requestId": "ff8bef06-a211-49aa-b169-cbc8e240b1d7",
    "metadata": {
        "App Team": {
            "groups": [
                "d704e672-b33c-4fda-b4fc-bde7a8774de4"
            ],
            "customMetadata": {
                "owner": "Dave"
            },
            "endpoints": [
                "770e4021-08f3-48d9-bdc1-ae9a8fd07cea"
            ]
        },
        "Data Team": {
            "groups": [
                "f9e4a3f1-b8e4-4ff6-8307-e414dfc69ddb"
            ],
            "customMetadata": {
                "owner": "Dan"
            },
            "endpoints": [
                "4f806937-6f5b-478e-a81a-f4b2ece14bb1"
            ]
        },
        "DevOps Team": {
            "groups": [
                "4b6f659e-6a7a-4dc4-975c-30a641f0a42b"
            ],
            "customMetadata": {
                "owner": "Sam"
            }
        }
    }
}

Bad Request

Unauthorized

Too many requests

Server unavailable

Gateway Timeout

Returns a JSON object with the following properties:

  • Request Id - The unique identifier for the API request.

  • Custom Metadata - Any metadata attached to the virtual tag.

PUT/Virtual Tag Metadata

Enrich your virtual tag values with groups and custom metadata by adding them to your virtual tag and specifying them per value. This metadata is also used with other objects in Finout.

Note:

  • Currently, using virtual tag values metadata is only available in Financial Plans.

  • Adding virtual tag metadata using the PUT query overrides the current data in the virtual tag.

  • Documentation to learn more about utilizing metadata in financial plans is coming soon.

Prerequisites

Request

https://app.finout.io/v1/virtual-tags/virtualtagID/metadata Use Case: Assume your organization has three teams: App Team, Data Team, and DevOps Team. You need to configure groups for each team and assign an owner name for each team.

{
    "App Team": {
        "groups": [
            "d704e672-b33c-4fda-b4fc-bde7a8774de4"
        ],
        "customMetadata": {
            "owner": "Dave"
        },
        "endpoints": [
            "770e4021-08f3-48d9-bdc1-ae9a8fd07cea"
        ]
    },
    "Data Team": {
        "groups": [
            "f9e4a3f1-b8e4-4ff6-8307-e414dfc69ddb"
        ],
        "customMetadata": {
            "owner": "Dan"
        },
        "endpoints": [
            "4f806937-6f5b-478e-a81a-f4b2ece14bb1"
        ]
    },
    "DevOps Team": {
        "groups": [
            "4b6f659e-6a7a-4dc4-975c-30a641f0a42b"
        ],
        "customMetadata": {
            "owner": "Sam"
        }
    }
}

Body of Request

Parameter

Type

Description

Virtual Tag Value

String

The object that defines the value for the virtual tag. This can be of any value. ​Limitation: Virtual tag values in this specific endpoint cannot include dots. For more information, see Virtual Tags.

customMetadata

Object

Any type of metadata can be attached to the virtual tag’s value. You must specify the custom metadata key and value.

Example:

If you want to assign an owner to a virtual tag’s value, you can set "owner" as the custom metadata key and "owner_name" as the custom metadata value. For more information, see Financial Plans.

groups

Array

The group of this specific value. You can use one or more groups.

To get account group IDs, contact your customer success representative. For more information, see Financial Plans.

endpoints

Array

An endpoint of this specific value. You can set one or more endpoints. ​Example: If the virtual tag’s value is "app team," you can provide the endpoint ID of the app team. ​{ "endpoint":"endpoint-app-team-id" }

To learn how to get a list of your account's endpoints, see Endpoint API. See Reports to learn how to send reports to various endpoints.

Response

{
    "requestId": "68849e84-6fe5-4605-939a-72ccdec138b6",
    "metadata": {
        "App Team": {
            "groups": [
                "d704e672-b33c-4fda-b4fc-bde7a8774de4"
            ],
            "customMetadata": {
                "owner": "Dave"
            },
            "endpoints": [
                "770e4021-08f3-48d9-bdc1-ae9a8fd07cea"
            ]
        },
        "Data Team": {
            "groups": [
                "f9e4a3f1-b8e4-4ff6-8307-e414dfc69ddb"
            ],
            "customMetadata": {
                "owner": "Dan"
            },
            "endpoints": [
                "4f806937-6f5b-478e-a81a-f4b2ece14bb1"
            ]
        },
        "DevOps Team": {
            "groups": [
                "4b6f659e-6a7a-4dc4-975c-30a641f0a42b"
            ],
            "customMetadata": {
                "owner": "Sam"
            }
        }
    },
    "request": {
        "virtualTagId": "d8026cec-6d3b-4c54-87f7-6ea815aa3b89"
    }
}

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 unique identifier for the API request.

  • Custom Metadata - Any metadata attached to the virtual tag.