Query Language API V2

The Query Language API V2 helps you discover the building blocks for filtering and querying your Finout cost data. Use it to retrieve available keys, inspect the types each key supports, and fetch valid values for a specific key.

This API is useful when you need to:

• Validate filter inputs before sending queries to the Cost and Usage API V2

• Identify which key type to use when building Virtual Tag rules and using the Virtual Tag API V2

---

Prerequisites

Before using the Query Language API V2, generate a Finout API token and include the following headers in every request:

• x-finout-client-id

• x-finout-secret-key

The same credentials are used across all Finout API endpoints.

---

How it works

The Query Language API V2 includes two endpoints:

• GET /v2/query-language/keys — returns all available keys and the types each key supports.

• GET /v2/query-language/values/{costCenter}/{key} — returns the valid values for a specific key.

You typically call these endpoints in this order:

1. Retrieve the available keys.

2. Identify the costCenter, key, and supported types for the field you need.

3. Retrieve the valid values for that key.

4. Use those values to build filters, Virtual Tag rules, or downstream cost queries.

---

Rate Limits

Endpoint	Rate Limit (per account, per route)
GET /v2/megabill/query-language/keys	50 req / min
GET /v2/megabill/query-language/values/{costCenter}/{key}	50 req / min

---

GET /Keys

Retrieves all available Query Language keys and their metadata.

Example use case: Populate a filter builder with all available dimensions before querying the Cost and Usage API V2.

Request

GET https://app.finout.io/v2/query-language/keys

Example response

{
  "requestId": "cce9ed72-cd36-4848-8017-34c0e3d8c859",
  "data": {
    "keys": [
      {
        "costCenter": "Kubernetes",
        "key": "deployment",
        "displayName": "deployment",
        "types": ["k8s_namespace"]
      },
      {
        "costCenter": "Oracle Cloud",
        "key": "sku_unit_description",
        "displayName": "SKU Unit Description",
        "types": ["tag"]
      },
      {
        "costCenter": "Custom Cost",
        "key": "customCost_Key_1",
        "displayName": "Key_1",
        "types": ["custom_cost"]
      }
    ]
  }
}

Response fields

Field	Type	Description
requestId	string	Unique identifier for the request.
data.keys	array	List of key objects.

Key object fields

Field	Type	Description
costCenter	string	Cost center associated with the key.
key	string	Key identifier.
displayName	string	Display name shown in Finout.
types	array of strings	List of supported types for the key. A key can support one or more types.

Supported types

Type	Description
tag	Tags from billing exports (e.g., AWS CUR tags / user-defined tags).
billing_dimension	Native billing export fields (CUR columns) such as service, sub-service, or cross-center fields.
resource	Resource identifiers and metadata (resource-level attributes).
billing_enrichment	Finout-enriched attributes added on top of native billing data (e.g., AWS Product Name).
virtual_tag	Finout Virtual Tags.
custom_cost	Custom cost datasets or user-defined lines.
kubernetes_resource	Kubernetes entity dimensions (cluster, workload, node, etc.).
k8s_pod_label	Labels attached to pods.
k8s_node_label	Labels attached to nodes.
k8s_namespace	Namespace attribute or namespace object.

---

GET /KeyValues

Retrieves all valid values for a specific key.

This endpoint accepts an optional type query parameter. Use it when a key supports multiple types and you want to retrieve values for a specific one.

Prerequisites

• Call GET /v2/query-language/keys first to retrieve valid costCenter, key, and types values.

• If the key has multiple types, include the type parameter using one of the returned values.

Request

GET https://app.finout.io/v2/query-language/values/{costCenter}/{key}?type={type}

Path parameters

Name	Type	Description
costCenter	string	Cost center identifier.
key	string	Key identifier.

Query parameters

Name	Type	Required	Description
type	string	No	Disambiguates the key when it supports multiple types.

If you omit type for a key that supports multiple types, Finout returns values for the first type listed in the key's types array. If you include type for a single-type key, it must match the key's supported type.

Success response

{
  "requestId": "d7f5c17e-2801-451e-a0bd-0bd459ced81c",
  "data": {
    "values": [
      "cold-fathom",
      "aged-reload",
      "lead-acre",
      "each-rate",
      "hard-nectarine"
    ]
  }
}

Success response fields

Field	Type	Description
requestId	string	Unique identifier for the request.
data.values	array of strings	Valid values for the requested key.

Error responses

Returned when you provide a type that the key does not support, or when the key has multiple types and you did not specify one.

{
  "requestId": "baf18230-bb1a-4761-802b-7c52e434a342",
  "message": "Invalid cost center, key or type provided",
  "code": "BAD_REQUEST"
}

{
  "requestId": "39d1c398-0056-4094-a8dc-60bb7c3a5607",
  "message": "Multiple types found for the requested key. Please specify type. Available types: k8s_pod_label, k8s_node_label",
  "code": "BAD_REQUEST"
}

Error fields

Field	Type	Description
code	string	Error code.
message	string	Human-readable error message.
requestId	string	Unique identifier for the request.

---

FAQs

When should I use the type query parameter? Use type when a key supports more than one type and you want to control which set of values is returned.

What happens if I omit type for a key with multiple supported types? Finout returns values for the first type listed in the key's types array.

Do I need to send type for a key that supports only one type? No. If you include it anyway, it must match the key's single supported type.

How do I know which keys are available for a cost center? Call GET /v2/query-language/keys first. The response includes all available keys, their display names, and the types each key supports.

How do I use this API with Virtual Tags or cost queries? Use the /keys endpoint to identify valid fields, then use the /values endpoint to retrieve allowed values for those fields. You can then use those values to build Virtual Tag rules in the Virtual Tag V2 API (coming soon) or filters for the Cost and Usage API V2.

What is the Global cost center? Global is a meta cost center for cross-provider dimensions that span multiple cost centers.