Placeholders

A placeholder is a special tag that you can insert into your connector configuration, which gets replaced with a dynamic value when the connector is used. Think of them as variables for your connector.

Placeholders are essential for building powerful connectors because most API requests require dynamic information. For example, you might need to:

Fetch data for a specific date range selected by the user.
Include a user's secret access token in an authentication header.
Pass a list of specific metrics and dimensions the user selected as part of the request.

Placeholders solve this problem by acting as a stand-in for that information. When a user uses the connector (meaning that the user authenticates or runs a query), all the placeholders defined in the connector get replaced with the correct, up-to-the-minute values.

A Simple Example: Dynamic Date Ranges

Let's say you're building a connector and the API requires a URL with start and end dates, like this: https://api.example.com/data?start=2025-01-01&end=2025-01-31

This URL is static. It will only ever fetch data for January 2025.

To make it dynamic, you can use date placeholders. You would write the URL in the connector configuration like this: https://api.example.com/data?start={{query.start_date.date}}&end={{query.end_date.date}}

Now, when a user selects a date range for their query in Supermetrics, the {{query.start_date.date}} and {{query.end_date.date}} placeholders will be automatically replaced with the selected dates. For example, if the user chose to fetch data for all of June 2025, the connector will automatically build the correct URL: https://api.example.com/data?start=2025-06-01&end=2025-06-30.

Using placeholders

The syntax is simple. Just wrap the placeholder's name in double curly braces, like {{placeholder_name}}. There is a pre-defined list of placeholders available, which you’ll find below.

Placeholders can be used within request URLs, or as request header, body, or parameter values.

Available Placeholders

Placeholders are grouped into several categories based on the type of information they provide.

User input placeholders

User input placeholders allow you to use values the user has input during the authentication flow.

Placeholder	Description
`inputs.*`	Input fields in the authentication flow. The asterisk is replaced by the ID of the input field. For example, for input field with ID `account_id`, the placeholder would be `{{inputs.account_id}}`.

Placeholder

Description

inputs.*

Input fields in the authentication flow. The asterisk is replaced by the ID of the input field.

For example, for input field with ID account_id, the placeholder would be {{inputs.account_id}}.

OAuth2 placeholders

OAuth2 placeholders are dedicated to the OAuth2 authentication type and make configuring OAuth2 authentication easier.

Placeholder	Description
`oauth2.client_id`	Client ID for OAuth2. Gets the value defined in the `clientId` property in the authentication configuration, so you can reuse the value in multiple places.
`oauth2.client_secret`	Client secret for OAuth2. Gets the value defined in the `clientSecret` property in the authentication configuration, so you can reuse the value in multiple places.
`oauth2.callback_url`	The callback URL you’re going to need for OAuth2 authentication. This will always return `https://supermetrics.com/login-complete` so the data source knows to return the authentication flow to the correct place in Supermetrics. If you need to have the callback URL with a trailing slash, you can use this format `{{oauth2.callback_url}}/`.
`oauth2.code`	The OAuth2 code used in the token exchange.
`oauth2.refresh_token`	The refresh token used when the OAuth2 token is refreshed.
`oauth2.state`	The state string for OAuth2 flow.

Data source user placeholders

Data source user placeholders allow you to use values and properties configured to be stored in the data source user component.

Placeholder	Description
`user.access_token`	Access token for the selected connection.
`user.credentials`	Base64 encoded string of `{oauth2 client ID}:{oauth2 client secret}`
`user.properties.*`	If you have defined additional properties in data source user component, you can use them via a placeholder by replacing the asterisk with any data source user property ID. NOTE: Currently unsupported in OAuth2 authentication

Placeholder

Description

user.access_token

Access token for the selected connection.

user.credentials

Base64 encoded string of {oauth2 client ID}:{oauth2 client secret}

user.properties.*

If you have defined additional properties in data source user component, you can use them via a placeholder by replacing the asterisk with any data source user property ID.

NOTE: Currently unsupported in OAuth2 authentication

Account placeholders

Account placeholders allow you to use values and properties from accounts fetched via account fetchers.

Placeholder	Description
`account.id`	ID of the currently used account.
`account.parent_id`	Parent account ID of the currently used subaccount.
`account.properties.*`	If you have defined additional properties in the accounts component, you can use them via placeholders by replacing the asterisk with any account property ID.

Query placeholders

Query-related placeholders allow you to use values selected by the user when building a query in Supermetrics. These include, for example, the start or end date selected for the query, the fields selected for the query, or the options selected for the query.

Placeholder	Description
`query.start_date.` & `query.end_date.`	Start and end date user selected for the query in the Supermetrics product. The asterisk `*` is replaced by the format you want to have the date formatted in. For example, `query.start_date.date` for format `2025-12-31`. Available formats: `date`: format `2025-12-31` `atom`: format `2025-12-31T00:00:00+02:00` `atom_utc`: format `2025-12-31T22:00:00Z`, where timezone is set to UTC. `timestamp`: format `1767132000` `year`: format `2025` `month`: format `12` `day`: format `31`
`query.settings.*`	The value the user selected for the setting when building a query in the Supermetrics product. The asterisk `*` is replaced by the ID of the setting to define which setting’s value is used.
`query.fields.as_comma_separated_string`	IDs of all the fields (metrics and dimensions) the user selected when building a query in Supermetrics products, as a comma-separated string. For example: `dim1,dim2,met1,met2`
`query.fields.as_space_separated_string`	IDs of all the fields (metrics and dimensions) the user selected when building a query in Supermetrics products as a space-separated string. For example: `dim1 dim2 met1 met2`
`query.dimensions.as_comma_separated_string`	IDs of all the dimensions the user selected when building a query in Supermetrics products as a comma-separated string. For example: `dim1,dim2`
`query.dimensions.as_space_separated_string`	IDs of all the dimensions the user selected when building a query in Supermetrics products as a space-separated string. For example: `dim1 dim2`
`query.metrics.as_comma_separated_string`	IDs of all the metrics the user selected when building a query in Supermetrics products as a comma-separated string. For example: `met1,met2`
`query.metrics.as_space_separated_string`	IDs of all the metrics the user selected when building a query in Supermetrics products as a space-separated string. For example: `met1 met2`

Asynchronous request flow placeholders

Async placeholders are used when configuring asynchronous request flow to use the report ID received during the initial report generation request when polling for status, and to use the endpoint/URL to get final results received from polling.

Placeholder	Description
`async.init.*`	The value received as a response from the initial reporting request (`init`) of the async request flow. Replace the asterisk `*` with the ID of the data property defined under the response of the `init` step of the async reporting flow.
`async.poll.*`	The value received as a response from the polling step (`poll`) of async request flow. Replace the asterisk `*` with the ID of the data property defined under the response of the `init` step of the async reporting flow.

Placeholder

Description

async.init.*

The value received as a response from the initial reporting request (init) of the async request flow.

Replace the asterisk * with the ID of the data property defined under the response of the init step of the async reporting flow.

async.poll.*

The value received as a response from the polling step (poll) of async request flow.

Replace the asterisk * with the ID of the data property defined under the response of the init step of the async reporting flow.

Placeholder operations

Placeholder operations are used to modify values given to them.

For example, if you want to subtract the first 5 characters from a username that the user provided as input during the authentication flow, you can add a placeholder operation around the placeholder to do so. The configuration would look like this: {{subst(inputs.username,0,5)

You can find all available operations and their explanation for the parameters below.

Using static strings in placeholder operations

You can also use static string values within placeholder operations where you need to. Static values can be included within operations by wrapping them in single quotes ' .

For example, if you want to use base64 encoded values of username and password stored in the data source users, and those should be separated by a semicolon :, the configuration would look like this: {{base64(user.properties.username,’:’,user.properties.password)}} .

Available operations

Operation	Description
`base64(…arguments)`	`base64()` accepts any number of arguments. The arguments are combined as a single string, and the string is then encoded with base64. Example: `{{base64(user.properties.uname, ':', user.properties.passw)}}`
`date(format, date)`	`format` accepts the same string formatting as PHP’s date function does. `date` can be any date string, which will be used as the base date for `format`. Example: `{{date('YmdHis', query.start_date.date)}}` will result to `20210601000000` for `query.start_date.date` being `2021-06-01`.
`format(pattern, value, separator)`	Returns a formatted string according to the provided `pattern`. `pattern` must be a string and must contain a value placeholder: `#VALUE#`. This placeholder will be replaced with the provided `value` `value` can be: any scalar value (int, float, string, or bool) array of scalar values null (empty) If `value` is an array, `pattern` will be applied to each array’s item, and all items will be combined into one string by using the provided `separator`. If `value` (including the array’s items) isn’t a scalar value, `pattern` won’t be applied, and formatting will be skipped. Examples `format('Hello #VALUE# World!', 'beautiful')` - returns `Hello beautiful World!` `format('Hello #VALUE# World!', ['beautiful', 'pretty'], ' and ')` - returns `Hello beautiful World! and Hello pretty World!`
`identity()`	Returns a globally unique string - identifier. It’s usually used to identify and distinguish each connection, or the User ID field of user info object when data source doesn't provide a suitable or secure one that can be exposed publicly. Example `identity()` result to `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`.
`ifempty(argument, valueOnTrue, valueOnFalse)`	Returns one value (`valueOnTrue`) if the provided argument is empty and another (`valueOnFalse`) if it is not. Empty argument is considered to be: boolean false integer 0 (zero) floats 0.0 and -0.0 (zero) empty string "", and the string "0" an array with zero elements NULL Example `{{ ifempty(query.metrics.array, '', concat('&metrics=', implode('&metrics=', query.metrics.array))) }}` will return an empty string if no metrics were selected. Otherwise, if metrics like `impressions`, `clicks` were selected, it will return a string `&metrics=impressions&metrics=clicks`
`implode(glue, array)`	`glue` defines the string to use to join the `array` elements. Example `{{implode(',', query.fields.all)}}` will join all query fields (metrics and dimensions) with commas. It will look something like this: `dimension1,dimension2,metric1`
`substr(string, start [, length])`	`string` is the string being processed. `start` defines the starting point (0 is the start of the string). `length` defines how many characters to get. If not defined, everything after `start` will be returned Example `{{substr('abcdef', 1, 2)}}` results to `bc`.
`time()`	Returns current timestamp. Example `time()` result to `1617867053`.
`trim(string [, charactersToTrim])`	`string` is the string being processed. `charactersToTrim` defines which characters will be removed from the beginning and the end of the `string`. If `charactersToTrim` is not defined, white-space characters will be trimmed: " " (ASCII 32 (0x20)), an ordinary space. "\t" (ASCII 9 (0x09)), a tab. "\n" (ASCII 10 (0x0A)), a new line (line feed). "\r" (ASCII 13 (0x0D)), a carriage return. "\0" (ASCII 0 (0x00)), the NUL-byte. "\v" (ASCII 11 (0x0B)), a vertical tab. Example `{{trim(' foobar! !', ' !')}}` results to `foobar`.
`formatasstringarray(array)`	Formats an array as a string containing an array of strings: `["display_name","profile_image","views"]`. If the passed parameter is not an array but a scalar value, like `some_scalar_value` or `123`, that value is returned as the first element of an array, such as `["some_scalar_value"]` or `["123"]`. Example `{{formatasstringarray(query.fields.array)}}` when `query.fields.array` contains `['display_name', 'profile_image', 'views']` results to `["display_name","profile_image","views"]`.
`strtolower(string)`	Returns `string` with all ASCII alphabetic characters converted to lowercase.
`strtotime(timeString, format)`	Creates a formatted time string based on the input time string. `timeString` is a relative string denoting time such as `-1 day`, `+2 weeks`, `-5 months` , and so on. `format` accepts the same string formatting as PHP’s date function does. Example `strtotime('-1 day', 'Y-m-d')`
`replace(search, replace, subject)`	Replace all occurrences of the search string with the replacement string Example `replace('pineapple', 'salami', 'pizza with pineapple')` - output: `pizza with salami`
`urlencode(string)`	URL-encodes string. It calls the PHP function urlencode() for doing that. Example `{{urlencode(user.properties.filter)}}` when `user.properties.filter` is `param=Complicated parameter Value with __[] data` results to `param%3DComplicated+parameter+Value+with+__%5B%5D+data`
`explodeandgetnthvalue(separator, string, elementNumber)`	Split the string by the separator to an `array` and return the nth element from that `array` . Note: The elements count starts from `0`. Example `explodeandgetnthvalue('#', 'apple#lemon#lime', 1)` - output: `lemon`
`md5(…arguments)`	`md5()` accepts any number of arguments. The arguments are combined as a single string, and the string is then hashed with md5 function. Accepted argument types: `null` scalars (`string`, `int`, `float`) objects implementing `\Stringable` Any other argument types will be ignored. Example: `{{md5(user.properties.username, ':', user.properties.password)}}` Given `user.properties.username=admin` and `user.properties.password=123`, the combined string will be `admin:123` and the operation will return `a4a07b60a109f55e301e5bb724b64d19`.
`concat(…arguments)`	`concat()` accepts any number of arguments. The arguments are combined as a single string. Example `{{concat('account name: ', account.properties.name)}}` Given `account.properties.name=Acme`, the result string will be `account name: Acme`
`firstnonempty(…arguments)`	`firstnonempty()` accepts any number of arguments. The first (from left to right) argument with a non-empty value will be returned, or an empty string if there is no such. Example `{{firstnonempty(user.properties.name, user.properties.email)}}` Given `user.properties.name='David Lynch', user.properties.email='divad.hcnyl@example.com'`, the result string will be `David Lynch` and given `user.properties.name='', user.properties.email='bob@example.com'` the result string will be `bob@example.com`.