Use variables and data sets

Write {{name}} once and let the workspace, environment, earlier steps or a data set fill it in.

In short

A variable is a name in double braces, such as {{baseUrl}} or {{token}}, that is filled in just before a request goes out. Values come from earlier steps, a data set, the request, the environment or the workspace. A data set runs a suite once for each row of data.

Before you start

Who: setting request variables and an environment's plain variables needs Edit on the project. An environment's secrets and settings need Manage. Workspace variables of an organization are changed by people who manage its settings.
Plan: every plan. A data set sends one run of every step per row, and each request counts toward your allowance.
First: have the environment ready, or the earlier step that keeps the value.

Steps

Write {{name}} in an address, a header, a body or a check. Type {{ to pick from the variables you can use.
Give it a value in the environment, in the request's setup variables, or with "Keep a value" on an earlier request.
Press "Send". The editor marks a name nothing defines before you send.

Values come from the first of these that has the name, nearest first:

Follow or stop a suite run

Open a suite and press "Run". The run starts at once and its steps appear as they finish.
Leave the screen if you like: the run goes on. Come back to the suite to see where it is.
To stop it, press "Stop run". It ends before its next step; what it finished is kept.

Result: a stopped run is marked Canceled and says why - stopped by a person, access to the project taken away, the plan's limit reached, or the server restarted. It never counts as a failure. You can have three suite runs going at once; the person who started a run, or someone who manages the project, can stop it.

Follow or stop Run all

Open a project and press "Run all", or pick rows and press "Run selected". The run starts at once.
The button counts up - "Running 4 of 20" - as each batch of requests finishes, and each row's result changes as it comes back.
Leave the board if you like: the run goes on. Come back and the board picks it up again.
To stop it, press "Stop run". It ends before its next batch; what it finished is kept.

Result: when the run ends, the line over the board shows what passed and failed. A stopped run says how far it got and why it stopped. Requests it did not send are not counted against your plan. You can have three project runs going at once; the person who started a run, or someone who manages the project, can stop it.

Fill a data set from a SQL Tester run

Open the suite and choose the "Data set" tab.
Press "From a SQL Tester run", and choose a project and a run that kept its rows.
Read the first rows. Each column becomes a variable, such as {{email}}.
Press "Use N rows". The suite then runs once for each row.

Result: real rows drive the suite, and you see only runs you may open in SQL Tester. The rows are copied into the suite, so choose a run again to refresh them. A data set holds 200 rows, and the screen says when rows were left out.

To keep the rows up to date without coming back, press "Follow a saved SQL query" and choose a query. It is read again before each run on the server, and a run from the command line uses the rows last read. A query that can no longer be read stops the run and says why.

Read a secret from your vault

Open the project's settings and choose "Vaults". Only people who manage the project see this tab.
Press "Connect a vault", choose HashiCorp Vault, Azure Key Vault or AWS Secrets Manager, and fill in the form. Use a credential that can read only what this project needs.
In "Environments", edit the environment and tick "Secret" on a variable.
Press "Read from a vault", choose the vault and give the path, and the field if the secret has one.
Press "Check". It says whether the secret was found and never shows it. Then save the environment.

Result: each run reads the secret from your vault and masks it like any other secret. {{brand}} stores no copy, and a rotated secret is picked up within a minute. A local run from the command line takes the value from its own machine. If the vault does not answer, the run stops before anything is sent, and a monitor marks that check as not sent.

See the ways a run failed

Run a suite, or press Run all on a project. When more than one thing fails, a "failures, ways" panel opens under the result.
Each row is one way of failing: how many times, which call, why, and whether earlier runs failed like that. Failures that broke the same way are one row, the most common first.
Press "Open run" on a row to read one of those failures.
Press "Why did this fail?" in the panel for one explanation of the whole run.

Result: you fix the cause behind most failures first. The list uses no AI and shows no value any call sent or got. The explanation is one AI question for the whole run, and asking again about the same failures uses none.

See whether a failure happened before

Open a failed run, or send a request that fails.
Under the response, read "Seen before". It is there only when an earlier call failed the same way: the same method and address pattern, the same status and the same failed checks.
Each of the newest three says when it failed, when the request passed again and whether the request was edited first. A bug card that followed it is shown too.
Press "What changed" to set that earlier failure beside the run that passed after it.

Result: you see at once whether this is new or an old failure coming back, and what fixed it last time. Only runs of projects you can open are counted, and no AI is used. "Why did this fail?" and "Create bug" mention it too.

Run a suite once for each row of data

Open a suite, then "Data set".
Press "Upload a file" or "Paste data": a CSV file whose first row names the columns, or a JSON list of objects. Check the preview of the first rows.
Press "Use these rows".
Run the suite.

Result: each column becomes a variable every step can use; each row has its own results, and the summary says how many rows passed and failed. Remove the data set and the suite runs once again.

Compare two environments

On a suite, choose "Compare two environments". Pick two different environments - for example staging and production - and press "Run both". Each step is set side by side with its status, its time and what changed in the body, secrets masked. Both runs are real runs that count like any other.

Variables made fresh each time

A dynamic variable has one value per request, so the address, the body and the checks of one request agree. The next request gets a new one.

Good to know

A variable nobody gives a value stays exactly as written, {{token}}, so a missing value shows up as a request that is clearly wrong.
"Workspace variables" sets values every project in your workspace can use. Each environment's own variables win over them. Only people who manage the organization's settings can change an organization's.
A data set can have up to 200 rows and 50 columns, and a file up to 256 KB. A run sends at most 2,000 steps in all.

Never put a secret in workspace variables Workspace variables are not secret. Keep passwords and tokens in an environment, where they are stored encrypted and only people who may use the project reach them.

Secrets

A secret variable's value is never shown in the web app - only its name - and a run masks it in everything it keeps. It never goes anywhere a person could copy it from. It is not in the list of variables, not under the address, not in a code snippet, and not out of your browser. Mark a variable Secret in the environment, or in a request's setup variables. Someone who can only run a project can send its secrets only to a host the project already names.

If something goes wrong

A request goes out with {{token}} as text: nothing defines the variable. Add it to the environment.
"Secret variable '...' needs a value.": give the secret a value in the environment.
"... could not be read" and a reason: the vault did not give the secret, so nothing was sent. Open the variable in the environment and press "Check".
"This data set would send more than 2,000 steps in one run. Use fewer rows or steps."
"The data set is not valid JSON: give an array of objects." / "Two columns of the data set have the same name."
"Workspace variables are shared with every project: keep secrets in an environment instead."
"The data set is empty." and "The data set has no rows.": add at least one row below the header.
"A data set can have at most 200 rows." and "A data set can have at most 50 columns.": use a smaller file.
"Every column of a CSV data set needs a name in the first row."
A message that ends "cannot be a variable name: use letters, digits, dashes, dots or underscores." names a column header to rename.
A message such as "Row 3 of the data set has more values than there are columns." names the line to fix. "A quoted value in the CSV data set is never closed." means a quote has no end.
"A project must keep at least one environment." and "The default environment must be enabled.": keep one environment on and make it the default.
"An environment cannot inherit from itself." and "Environment inheritance cannot contain a cycle.": choose a parent that does not lead back.
"Someone else changed this": someone saved the request, or the same environment variable or setting you changed, after you opened it. Reload shows their version; Keep mine saves yours over it. Anything else saved to an environment meanwhile - another variable, another setting, or a token a run wrote back - is kept beside your change, and the saved message says so.
Saved the wrong change to a request: "Undo" in the Saved message puts back the request as it was before that save. If someone saved it again in between, the Undo is refused rather than overwriting their change.
"Another environment became the default meanwhile.": someone made another environment the default at the same moment. Reload the environments and try again.
"The environment kept changing while this run saved what it extracted.": run it again; the values already saved stay.

/help/api-testing/request-editor-and-checks
/help/api-testing/test-suites
/help/api-testing/authentication