# 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](https://docs.finout.io/api/finout-api/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](https://docs.finout.io/api/finout-api/generate-an-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**

```json
{
  "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](https://docs.finout.io/user-guide/inform/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. |

{% hint style="info" %}
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.
{% endhint %}

**Success response**

```json
{
  "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.

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

```json
{
  "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](https://docs.finout.io/api/finout-api/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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.finout.io/api/finout-api/finout-api-v2/query-language-api-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.