rq.environment (Environment variables)

Complete reference for the rq.environment object in Requestly scripts to manage environment variables dynamically during API request execution.

The rq.environment object reads and changes environment variables from a script. Environment variables belong to one environment, and every request reads them while that environment is active.

​

Methods

​

rq.environment.get(key)

Returns the value of a variable in the active environment.

Parameters:

• key (string): The variable’s name

Returns: The value, or undefined if the variable does not exist or is disabled. A number, boolean or array variable comes back as that type. A variable you set earlier in the same script comes back as set stored it.

Example:

const token = rq.environment.get("authToken");
console.log("Token:", token);

​

rq.environment.set(key, value, type?)

Creates or updates a variable in the active environment.

Parameters:

• key (string): The variable’s name. It must not be empty.
• value (any): The value to store. A variable that already exists converts the value to its type: set("count", "42") on a number variable stores 42. A new variable keeps the value exactly as you pass it. null or undefined removes the variable, the same as unset(key).
• type (string, optional): The type to give the variable before the value is stored: "string", "number", "boolean", "array", "object" or "any". You can also pass { type }.

See How values are saved for what the next request reads.

Example:

rq.environment.set("authToken", "Bearer <TOKEN>");
rq.environment.set("ids", ["a", "b"], "array");

​

rq.environment.has(key)

Checks whether a variable exists in the active environment and is enabled.

Parameters:

• key (string): The variable’s name

Returns: true if the variable exists and is enabled, otherwise false.

Example:

if (!rq.environment.has("authToken")) {
  console.log("No token yet");
}

​

rq.environment.unset(key)

Removes a variable from the active environment. A disabled variable is left alone.

Parameters:

• key (string): The variable’s name. It must not be empty.

Example:

rq.environment.unset("authToken");

​

rq.environment.clear()

Removes every variable from the active environment, disabled ones included.

Example:

rq.environment.clear();

​

rq.environment.toObject()

Returns the enabled variables of the active environment as one object of names and values. Disabled variables are left out.

Returns: An object such as { baseUrl: "https://api.example.com", retries: 3 }. Each value has the type get returns for it.

Example:

const all = rq.environment.toObject();
console.log("Variables:", Object.keys(all));

​

rq.environment.replaceIn(template)

Replaces each {{name}} in a template with the value of that variable in the active environment.

Parameters:

• template (string, object or array): Text containing {{name}} references. In an object or an array, every string inside is replaced.

Returns: The template with the references replaced. A value that is not text is written the way JavaScript’s String() writes it, so an array becomes a,b. A name with no enabled variable, and a dynamic variable such as {{$guid}}, stays as written. Each reference is replaced once, so a {{name}} inside a value stays as written. To replace names from every scope, use rq.variables.replaceIn.

Example:

const path = rq.environment.replaceIn("/users/{{userId}}");

​

rq.environment.toObjectResolved(scope?, overrides?)

Returns a plain copy of rq.environment, the same as toJSON(), with every {{name}} inside it replaced. For a plain object of names and values, use toObject().

Parameters:

• scope (object, optional): The object whose replaceIn replaces the references. Pass rq.variables to replace names from every scope. Defaults to rq.environment.
• overrides (array of objects, optional): Objects whose properties are copied onto the result, in order.

Returns: An object with id, name (when an environment is selected), values and mutations.

Example:

const resolved = rq.environment.toObjectResolved(rq.variables);
resolved.values.forEach((item) => console.log(item.key, item.value));

​

rq.environment.toJSON()

Returns a plain copy of rq.environment. JSON.stringify(rq.environment) uses it.

Returns: An object with:

• id: The same as rq.environment.id
• name: The environment’s name, when an environment is selected
• values: An array of { key, value, type } items, one per variable, with disabled: true on a disabled variable. An array variable’s value is its JSON text.
• mutations: The changes this script recorded, as { stream, compacted, autoCompact }

Example:

console.log(JSON.stringify(rq.environment));

​

rq.environment.syncVariablesFrom(object, track?)

Copies the names and values of a plain object into the active environment. An existing variable gets the new value, converted to its type, and a new name becomes a new variable. Variables the object does not name are kept. The changes are saved the same way as set, but are not recorded in mutations.

Parameters:

• object (object): The names and values to copy in
• track (boolean, optional): Set to true to get back what changed

Returns: With track set to true, an object that maps each new name to "created" and each name whose value changed to "updated". A name whose value did not change is not listed. Without track, undefined.

Example:

// "retries" exists and "region" does not
const changes = rq.environment.syncVariablesFrom({ region: "eu", retries: 5 }, true);
console.log(changes); // { region: "created", retries: "updated" }

​

rq.environment.syncVariablesTo(object?)

Copies every variable of the active environment, disabled ones included, into a plain object.

Parameters:

• object (object, optional): The object to copy into. Any key in it that the environment does not hold is deleted from it. Without it, a new object is used.

Returns: The object, with one property per variable. Each value has the type get returns for it.

Example:

const copy = rq.environment.syncVariablesTo();
console.log(copy.baseUrl);

​

rq.environment.values

The active environment’s variables, as a list. Unlike get, has and toObject, the list includes disabled variables.

Each item is one variable with key, value, type and disabled. Call the item’s get() to read its value as its type, since an array variable’s value is its JSON text, and its set(value) to change it.

The list has these methods:

• Read: one(key) returns the variable with that name, and get(key) its value. has(key) checks whether the list holds that name. count() returns the number of variables, all() an array of them, idx(index) the one at a position, and indexOf(key) its position, or -1. toObject() returns an object of names and values, and toJSON() an array of plain { key, value, type } items.
• Loop: each(fn), map(fn), filter(fn), find(fn) and reduce(fn, initial) work like the array methods of the same name. fn receives each variable and its position.
• Change: add({ key, value, type, disabled }) adds a variable. upsert({ key, value, type, disabled }) updates the variable with that name, or adds it when there is none. remove(key) removes the variable with that name, and remove(fn) removes every variable fn returns true for. clear() removes every variable.
• Text: replace(text) replaces each {{name}} in text with the list’s value for that name.
• Copy: syncFromObject(object, track?, prune?) works like syncVariablesFrom, and with prune set to true it also removes the variables the object does not name. syncToObject(object?) works like syncVariablesTo.

Changes made through values are saved the same way as set, but are not recorded in mutations.

Example:

rq.environment.values.each((variable) => {
  console.log(variable.key, variable.get(), variable.disabled === true);
});
rq.environment.values.upsert({ key: "region", value: "eu" });

​

rq.environment.id

The active environment’s id. When no environment is selected, a random id that is new each time a script runs.

Example:

console.log(rq.environment.id);

​

rq.environment.name

The active environment’s name, or undefined when no environment is selected. Only rq.environment has a name.

Example:

console.log("Running in", rq.environment.name);

​

rq.environment.mutations

A record of the set and unset calls this script made on rq.environment, in order. Recording is on from the start of the script. clear() records an unset for each variable it removes, and applyMutation records the call it makes. Changes made through values or syncVariablesFrom are not recorded.

• stream (array): One entry per call: [key, value] for set and [key] for unset. value is what you passed, before any conversion.
• compacted (object): The last change to each name, filled by compact() or by autoCompact
• count(): Returns the number of recorded changes
• compact(): Keeps only the last change to each name, moving the entries from stream into compacted
• applyOn(target): Makes the recorded changes again on another object, such as rq.globals

Example:

rq.environment.set("token", "abc");
rq.environment.unset("oldToken");
console.log(rq.environment.mutations.stream); // [["token", "abc"], ["oldToken"]]

// Make the same changes to the global variables
rq.environment.mutations.applyOn(rq.globals);

​

rq.environment.enableTracking(options?)

Starts recording set and unset calls in mutations. Recording is already on when a script starts, so calling this does nothing until you call disableTracking(). After that, it starts a new, empty record.

Parameters:

• options (object, optional): { autoCompact: true } keeps only the last change to each name, in mutations.compacted

Example:

rq.environment.disableTracking();
rq.environment.enableTracking({ autoCompact: true });
rq.environment.set("page", 1);
rq.environment.set("page", 2);
console.log(rq.environment.mutations.compacted); // { page: ["page", 2] }

​

rq.environment.disableTracking()

Stops recording changes in mutations. What was already recorded stays in mutations.

Example:

rq.environment.disableTracking();

​

rq.environment.applyMutation(instruction, key, value?)

Makes one change, named by instruction: "set" calls set(key, value) and "unset" calls unset(key). Any other instruction does nothing.

Parameters:

• instruction (string): "set" or "unset"
• key (string): The variable’s name
• value (any, optional): The value, for "set"

Example:

rq.environment.applyMutation("set", "region", "eu");

​

rq.environment.addLayer(list)

Adds a list of variables to read when the active environment has no enabled variable of that name. get, has, toObject and replaceIn read the lists in the order you add them. Writes still go to the active environment only.

Parameters:

• list: Another object’s values, such as rq.globals.values

Example:

rq.environment.addLayer(rq.globals.values);
const version = rq.environment.get("appVersion"); // the global value when the environment has none

​

How values are saved

Within one script, get returns the value set stored: exactly what you passed for a new variable, or the converted value for a variable that already has a type (see Typed variables). When the script ends, the value is saved, and the next request reads the saved form:

The value	The next request reads
A string, number or boolean	The same value, with the same type
NaN or Infinity	Its text, "NaN" or "Infinity"
An array	The same array, as an array variable
An object	Its JSON text, as a string
A Date	Its ISO text, such as "2026-01-31T09:00:00.000Z"
A Set or Map	"{}"
An Error	'{"type":"Error","name":"Error","message":"..."}'
null or undefined	Nothing: the variable is removed

Inside an array or an object, each item is written the way JSON.stringify writes it. A BigInt, or an object that refers to itself, cannot be written as JSON, so set stops the script with an error.

To keep an object, save it as text and parse it when you read it back:

rq.environment.set("user", JSON.stringify({ id: 42, role: "admin" }));

// In a later request
const user = JSON.parse(rq.environment.get("user"));
console.log(user.role); // "admin"

​

Typed variables

A variable that already exists has a type: string, number, boolean, array or secret. A string variable takes any value, the same as a new variable: a number stays a number, an array stays an array, and an object stays an object for the rest of the script. On the other types, set converts the value you pass, the way JavaScript’s String(), Number() and Boolean() convert:

• On a secret variable, the value becomes text: 42 becomes "42", and an object becomes "[object Object]".
• On a number variable, text that is not a number becomes NaN, and the next request reads the text "NaN".
• On a boolean variable, any non-empty string, even "false", becomes true. Pass true or false instead.
• On an array variable, pass an array, or its JSON text such as '["a","b"]'. Any other value, such as "a,b" or 5, reads back as undefined, and the variable is removed when the script ends.

To store a different kind of value, pass the type as the third argument. The variable takes that type first, then stores the value.

// "retries" is a number variable
rq.environment.set("retries", "3");
rq.environment.get("retries"); // 3, a number

// Give it another type as you set it
rq.environment.set("retries", "3", "string");
rq.environment.get("retries"); // "3"

​

Disabled variables

get, has and toObject skip a variable you have disabled, and replaceIn leaves its {{name}} as written. set on a disabled variable changes its value but leaves it disabled, so get still returns undefined until you enable it. unset leaves a disabled variable alone, and clear removes it with the rest. The values list and syncVariablesTo include disabled variables.

​

Working with array variables

An array variable holds a list of values. get returns it as a real array, not as comma-joined text:

rq.environment.set("ids", ["a", "b", "c"], "array");

const ids = rq.environment.get("ids");
console.log(Array.isArray(ids)); // true
console.log(ids[0]); // "a"

An array you pass to set stays an array on a new, string or array variable. On a number, boolean or secret variable it is converted, so pass "array" as the type, as above (see Typed variables).

You can also read the first or last items with .first() and .last():

const ids = rq.environment.get("ids");
ids.first(); // "a"
ids.last(); // "c"
ids.first(2); // ["a", "b"]
ids.last(2); // ["b", "c"]

​

Common Use Cases

​

Store Authentication Token

After receiving a login response, store the auth token for use in subsequent requests:

// In post-response script
const responseData = rq.response.json();
if (responseData.token) {
  rq.environment.set("authToken", "Bearer " + responseData.token);
  console.log("Auth token saved to environment");
}

A script is the right tool when the value has to refresh on every run. For a one-off capture, you can set a response value as a variable from the right-click menu instead.

​

Auto Increment Page Numbers

Increment a page number for pagination. Number() turns the value into a number whether the variable is a number or a string variable:

// In pre-request script
const currentPage = Number(rq.environment.get("page_number") || 1);
rq.environment.set("page_number", currentPage + 1);
console.log("Next page:", currentPage + 1);

​

Store API Response Data

Extract and store data from API responses for use in other requests:

// In post-response script
const data = rq.response.json();
rq.environment.set("user_id", data.id);
rq.environment.set("user_email", data.email);
rq.environment.set("created_at", data.created_at);

​

Conditional Token Management

Check whether a token exists before you rely on it:

// In pre-request script
if (!rq.environment.has("authToken")) {
  console.error("Auth token not found! Please login first.");
} else {
  console.log("Using existing auth token");
}

​

Clean Up Sensitive Data

Remove sensitive information after use:

// After completing authenticated requests
rq.environment.unset("authToken");
rq.environment.unset("password");
console.log("Sensitive data cleared from environment");

​

Track Request Counts

Keep track of how many times a request has been made:

// In post-response script
const requestCount = Number(rq.environment.get("request_count") || 0);
rq.environment.set("request_count", requestCount + 1);
console.log("This request has been made", requestCount + 1, "times");

​

Best Practices

1. Use Descriptive Names: Choose clear, descriptive names for environment variables (e.g., authToken instead of token)

2. Check for Existence: Check that a variable exists before using it:

   if (rq.environment.has("myVar")) {
     // Use rq.environment.get("myVar")
   } else {
     console.error("Variable not found");
   }
   

3. Clean Up: Remove sensitive data with unset() once you are done with it

4. Type Handling: A number, boolean or array variable comes back as that type, and a string variable as a string. Convert a string variable when you need a number:

   const pageNum = Number(rq.environment.get("page_number"));
   

​

Related Documentation

• Pre-request & Post-response Scripts
• rq.variables Object (reads every scope)
• rq.collectionVariables Object
• rq.globals Object
• rq.iterationData Object
• rq.sendRequest Object
• rq.execution Object
• rq.request Object
• rq.response Object
• rq.vault Object
• rq.test Object
• rq.expect Object