Expressions
This page gives the exact rules for data references and functions in step settings. For an introduction, read Using data from earlier steps first.
Where the data comes from
| Start with | Refers to | Example |
|---|---|---|
$trigger.output | The output of the trigger that started this run. | $trigger.output.email |
$trigger.type | Which trigger started this run, such as webhook or manual. | $trigger.type |
$.<step ID>.output | The output of an earlier step. | $.01JA9F3K7Q2M8XVBC4RTE5NHWD.output.text |
$execution.<name> | A detail of the current run. See Run details. | $execution.runId |
A step's ID is shown when you copy a reference from the $ list. Step IDs don't change when you rename a step.
Paths
After the root, add names to go deeper into the data:
| Syntax | Meaning | Example |
|---|---|---|
.name | A field. Letters, numbers, _ and - only. | $trigger.output.customer.email |
['name'] or ["name"] | A field whose name has spaces or other characters. | $trigger.output['First Name'] |
[n] | The item at position n in a list, counting from 0. | $trigger.output.items[0] |
[-n] | The nth item from the end of a list. [-1] is the last. | $trigger.output.items[-1] |
[reference] | A position taken from another reference. | $.<list step>.output.rows[$.<loop step>.output.currentIndex] |
If a position given by another reference can't be found, the first item, [0], is used.
How a field is filled in
AI Studio looks at the whole field to decide how to fill it in:
| The field contains | Result |
|---|---|
| A single reference and nothing else | The value with its type kept: text, number, yes/no, list or object. |
| References mixed with text | Text. Each reference is replaced by its value. Lists and objects are written as JSON, and an empty value becomes empty text. |
| A JSON object or list with references in its values | The same JSON, with each reference replaced. |
An expression starting with a function, such as $count(...) | The result of the expression, with its type kept. |
When a value is missing
| Situation | Whole-field reference | Reference inside text |
|---|---|---|
| The step didn't run in this execution | The reference text, unchanged | The reference text, unchanged |
| The step ran, but the field doesn't exist | Empty (null) | Empty text |
| The field is an empty list | [] | [] |
A missing value never fails the step by itself. The step runs with whatever it got, so check required values with a Path step when it matters.
Functions
Functions transform values. A field is evaluated as an expression only when the whole field starts with a function, for example $uppercase($trigger.output.name). Inside other text, a function is left as plain text.
Functions can be nested and can take references as arguments:
$join($split($trigger.output.tags, ","), " / ")
$round($sum($trigger.output.items.price) * 1.1, 0)In the second example, $trigger.output.items.price collects the price of every item into a list.
Expressions use JSONata, and the Functions tab lists the most useful ones:
Text
| Function | Returns |
|---|---|
$string(value) | The value as text. |
$length(text) | The number of characters. |
$substring(text, start, length) | Part of the text, starting at position start (from 0). |
$substringBefore(text, chars) | The text before the first chars. |
$substringAfter(text, chars) | The text after the first chars. |
$uppercase(text) / $lowercase(text) | The text in upper or lower case. |
$trim(text) | The text without extra spaces. |
$pad(text, width, char) | The text padded to width characters. A negative width pads on the left. |
$contains(text, pattern) | true if the text contains pattern. |
$split(text, separator) | A list of the parts between each separator. |
$join(list, separator) | One piece of text from a list. |
$match(text, pattern) | The matches of a regular expression. |
$replace(text, pattern, replacement) | The text with pattern replaced. |
$base64encode(text) / $base64decode(text) | The text encoded in or decoded from Base64. |
$encodeUrlComponent(text) / $decodeUrlComponent(text) | The text made safe for a URL query value, or turned back. |
$encodeUrl(text) / $decodeUrl(text) | A whole URL made safe, or turned back. |
$json(value) | The value as JSON text. Useful for sending an object in a text field. |
Numbers
| Function | Returns |
|---|---|
$number(value) | The value as a number. |
$abs(n), $floor(n), $ceil(n) | The absolute value, or n rounded down or up. |
$round(n, places) | n rounded to places decimal places. |
$power(base, exponent), $sqrt(n) | Powers and square roots. |
$random() | A random number from 0 to 1. |
$formatNumber(n, picture) | n as text in a format, such as $formatNumber(1234.5, "#,##0.00") → 1,234.50. |
$formatInteger(n, picture) / $parseInteger(text, picture) | Whole numbers to and from formatted text. |
$formatBase(n, radix) | n in another base, such as 16 for hexadecimal. |
$sum(list), $max(list), $min(list), $average(list) | Totals and statistics of a list of numbers. |
Lists
| Function | Returns |
|---|---|
$count(list) | The number of items. |
$append(list1, list2) | One list with the items of both. |
$sort(list) | The list in order. |
$reverse(list) | The list in reverse order. |
$shuffle(list) | The list in random order. |
$distinct(list) | The list without duplicates. |
$zip(list1, list2, …) | A list of lists, pairing items at the same position. |
Objects
| Function | Returns |
|---|---|
$keys(object) | The names of the object's fields. |
$lookup(object, name) | The value of the field called name. |
$spread(object) | A list with one object per field. |
$merge(list) | One object with the fields of every object in the list. |
$sift(object, function) | The object with only the fields the function accepts. |
$each(object, function) | A list with the function's result for each field. |
Yes / no
| Function | Returns |
|---|---|
$boolean(value) | The value as true or false. |
$not(value) | The opposite. |
$exists(value) | true if the value exists. |
Dates and times
| Function | Returns |
|---|---|
$now() | The current date and time, such as 2026-10-26T09:30:00.000Z. |
$now(picture, timezone) | The current date and time in a format and time zone, such as $now("[Y0001]-[M01]-[D01]", "+0900"). |
$millis() | The current time in milliseconds since 1 January 1970. |
$fromMillis(ms, picture, timezone) | Milliseconds turned into a formatted date. |
$toMillis(text) | A date in text turned into milliseconds, useful for comparing or adding to dates. |
Working with each item
These take a function that runs once per item. $v is the item:
| Function | Example | Returns |
|---|---|---|
$map(list, function) | $map($trigger.output.items, function($v) { $v.price * 2 }) | A list of each result. |
$filter(list, function) | $filter($trigger.output.items, function($v) { $v.stock > 0 }) | The items for which the function is true. |
$single(list, function) | $single($trigger.output.users, function($v) { $v.id = "u_42" }) | The one item for which the function is true. |
$reduce(list, function, start) | $reduce($trigger.output.items, function($total, $v) { $total + $v.price }, 0) | One value built up from every item. |
For everything else JSONata can do, see the JSONata documentation.
Run details
| Reference | Value |
|---|---|
$execution.flowId | The flow's ID. |
$execution.flowName | The flow's name. |
$execution.flowVersion | The flow version that's running. |
$execution.runId | This run's ID. Use it to find the run in Executions. |
$execution.orgId | Your organization's ID. |
$execution.workspaceId | The workspace's ID. |
$execution.triggerType | The kind of trigger that started the run. |
$execution.startedAt | When the run started. |
$execution.callbackURL.<Wait step ID> | The URL that resumes a Wait For Webhook step in this run. |
These values are filled in only when the reference is the whole field. In Run: $execution.runId, the reference stays as plain text.