---
title: "Query settings"
slug: "query-settings"
updated: 2026-10-27T15:51:01Z
published: 2026-10-27T15:51:01Z
canonical: "docs.supermetrics.com/query-settings"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query settings

Query settings let the user configure characteristics of a query — for example a reporting timezone, a currency, or a filter. They're defined per report type under a `settings` object, and the value the user selects becomes available in requests through the `{{query.settings.<ID>}}` placeholder.

Each setting is an item under `settings.items`:

| Field | Required | Description |
| --- | --- | --- |
| `id` | Yes | Unique identifier for the setting. This is the `<id>` used in the `{{query.settings.<id>}}` placeholder. |
| `label` | Yes | The label shown to the user. |
| `type` | Yes | The input type: `select`, `radio`, `checkbox`, `text`, or `textarea`. |
| `description` | No | Help text shown with the setting. |
| `isRequired` | No | Whether the user must give the setting a value. |
| `showEmptyValue` | No | Whether to show an empty value as the first option in a dropdown. |
| `options` | No | A fixed list of options (for `select`). Each option must have a `label` and a `value`, and optionally `isDefault: true` and `parameters`. |
| `dynamicOptions` | No | Options fetched from the data source at runtime, instead of a fixed `options` list. |

## Choosing a type

- Use `select` when the user picks from a set of known values, e.g. currency, device, or timezone. This is the most common and powerful type, and the only one that supports per-option parameters (see below).
- Use `text` (single-line) or `textarea` (multi-line) for free-form values the user types in.
- Use `checkbox` for a simple on/off toggle.

## Static options

When the list of choices is fixed, define them with `options`:

```
"settings": {
  "items": [
    {
      "id": "currency",
      "label": "Currency",
      "type": "select",
      "isRequired": true,
      "options": [
        {
          "label": "EUR",
          "value": "EUR",
          "isDefault": true
        },
        {
          "label": "USD",
          "value": "USD"
        }
      ]
    }
  ]
}
```

The selected value is referenced in a request with `{{query.settings.currency}}` — for example as a query parameter:

```
{
  "name": "currency",
  "value": "{{query.settings.currency}}"
}
```

### Attaching parameters to an option

Sometimes one setting selection needs to provide several different values, used in different places in the request — for example a timezone where the API wants both a timezone name in one field and a numeric timezone ID in another. Instead of encoding multiple values into the single `value` and splitting them apart later, give each option a set of named `parameters` (key/value pairs):

```
"settings": {
  "items": [
    {
      "id": "timezone",
      "label": "Timezone",
      "type": "select",
      "isRequired": true,
      "options": [
        {
          "label": "UTC",
          "value": "UTC",
          "isDefault": true,
          "parameters": [
            {
              "name": "timezone_name",
              "value": "UTC"
            },
            {
              "name": "timezone_id",
              "value": "11"
            }
          ]
        },
        {
          "label": "US/Central",
          "value": "US/Central",
          "parameters": [
            {
              "name": "timezone_name",
              "value": "US/Central"
            },
            {
              "name": "timezone_id",
              "value": "423"
            }
          ]
        }
      ]
    }
  ]
}
```

You then reference each value from the selected option independently — for example in a POST request body:

```
"request": {
  "method": "POST",
  "url": "https://api.example.com/report",
  "body": {
    "type": "json",
    "content": {
      "timezone": {
        "name": "{{query.settings.timezone.timezone_name}}",
        "id": "{{query.settings.timezone.timezone_id}}"
      }
    }
  }
}
```

How the placeholders resolve:

- `{{query.settings.<id>}}` — the selected option's required `value` attribute.
- `{{query.settings.<id>.<parameter_name>}}` — the value of a named parameter on the selected option.

> **Note:** An option's `value` is always required. You can either reuse `value` as one of your values and reference it with `{{query.settings.<id>}}`, or set `value` to anything, leave it unused, and define all the values you actually need under `parameters`. The second approach is recommended when an option carries multiple values — it keeps each value explicit and separately addressable.

## Dynamic options

When the available options can't be known in advance — for example a list of the user's own clients or currencies — use `dynamicOptions` instead of `options`. Each defines a `request` that fetches the list of options, and an `optionInfo` that maps each returned item to a `label` and a `value`:

```
"settings": {
  "items": [
    {
      "id": "currency",
      "label": "Currency",
      "type": "select",
      "isRequired": true,
      "dynamicOptions": [
        {
          "request": {
            "url": "https://example.com/api/currencies",
            "response": {
              "dataRows": {
                "source": "jsonPath",
                "value": "$.items.*"
              }
            }
          },
          "optionInfo": {
            "label": {
              "source": "jsonPath",
              "value": "$.name"
            },
            "value": {
              "source": "jsonPath",
              "value": "$.id"
            }
          }
        }
      ]
    }
  ]
}
```

> **Note:** Dynamic options are fetched at the connection level. The fetch request can use connection-level values such as the access token (`{{user.access_token}}`) and data source user properties, but it has no account in scope, so dynamic options can't be fetched per account. If your options depend on a specific account, they can't be loaded this way.