rq.collectionVariables (Collection variables)

​

Which collection a script writes to

• Reading looks up the chain and the nearest collection wins. A request in My Collection › Auth › Login sees Auth’s value for a name if there is one, otherwise the root collection’s.
• Writing targets the root collection by default, no matter how deeply the request is nested.

// A request in: My Collection › Auth › Login
rq.collectionVariables.set("token", value); //                       → My Collection (root)
rq.collectionVariables.set("token", value, { level: "root" }); //    → My Collection (same thing, explicit)
rq.collectionVariables.set("token", value, { level: "current" }); // → Auth

​

Methods

​

rq.collectionVariables.set(key, value, options?)

• key (string): The name of the collection variable
• value (any): The value to store. Scalar values are stored as strings; passing an array stores a real array, so a later get returns the array unchanged. Passing null or undefined clears the variable, which is equivalent to unset(key), so a later get returns undefined (not the string "null").
• options (object, optional): { level }: "root" (default) writes to the root collection, "current" writes to the collection the request sits directly inside. See Which collection a script writes to.

rq.collectionVariables.set("basePath", "/v1/users");

// Write to the sub-collection this request lives in, rather than the root
rq.collectionVariables.set("basePath", "/v1/users", { level: "current" });

​

rq.collectionVariables.get(key)

• key (string): The name of the collection variable to retrieve

const path = rq.collectionVariables.get("basePath");
console.log("Collection Variable basePath:", path);

​

rq.collectionVariables.unset(key, options?)

• key (string): The name of the collection variable to remove
• options (object, optional): { level }: "root" (default) or "current", the same as set(). Removes the copy held by that collection.

rq.collectionVariables.unset("basePath");

// Remove the copy held by this request's own sub-collection
rq.collectionVariables.unset("basePath", { level: "current" });

​

rq.collectionVariables.clear(options?)

• options (object, optional): { level }: "root" (default) clears the root collection’s own variables, "current" clears those of the collection the request sits directly inside.

rq.collectionVariables.clear();
console.log("Root collection variables cleared");

// Clear only this request's own sub-collection
rq.collectionVariables.clear({ level: "current" });

​

Common Use Cases

​

Store API Base Path

// In pre-request script
rq.collectionVariables.set("basePath", "/api/v2");
rq.collectionVariables.set("apiVersion", "v2");

{{baseUrl}}{{basePath}}/users

​

Share Data Between Collection Requests

// In the first request's post-response script
const data = rq.response.json();
rq.collectionVariables.set("createdResourceId", data.id);
rq.collectionVariables.set("resourceName", data.name);

// In the next request's pre-request script
const resourceId = rq.collectionVariables.get("createdResourceId");
console.log("Using resource ID:", resourceId);

​

Store Default Values

// In pre-request script
const pageSize = rq.environment.get("pageSize") || 
                 rq.collectionVariables.get("defaultPageSize") || 
                 "20";
console.log("Using page size:", pageSize);

​

Track Collection State

// Track if authentication has been completed
const isAuthenticated = rq.collectionVariables.get("isAuthenticated");
if (!isAuthenticated) {
    console.log("Need to authenticate first");
    rq.collectionVariables.set("isAuthenticated", "true");
}

​

Store Computed Values

// In pre-request script
const timestamp = Date.now();
const signature = generateSignature(timestamp); // Your custom function

rq.collectionVariables.set("requestTimestamp", timestamp);
rq.collectionVariables.set("requestSignature", signature);

​

Best Practices

1. Naming Convention: Use clear, descriptive names that indicate the variable’s purpose
   rq.collectionVariables.set("authBaseEndpoint", "/auth");
   rq.collectionVariables.set("apiVersion", "v2");
   
2. Initialize in Setup Requests: Create a setup or initialization request that sets default collection variables
3. Validate Before Use: Check if a variable exists before using it
   const value = rq.collectionVariables.get("myVar");
   if (!value) {
       console.error("Collection variable 'myVar' not found");
   }
   
4. Clean Up: Remove variables that are no longer needed
   rq.collectionVariables.unset("temporaryData");
   
5. Document Variables: Add comments in your scripts explaining what each variable is for
   // Store the created user ID for use in subsequent requests
   rq.collectionVariables.set("userId", data.id);
   

​

Related Documentation

• Pre-request & Post-response Scripts
• rq.sendRequest Object
• rq.execution Object
• rq.request Object
• rq.response Object
• rq.environment Object
• rq.globals Object
• rq.vault Object
• rq.test Object
• rq.expect Object