Run Collections with Custom Data

Learn how to use CSV or JSON data files with the Requestly Collection Runner to iterate requests with multiple input values.

You can use custom data files (CSV or JSON) when running a collection manually in Requestly.
This enables you to iterate through your requests using multiple sets of input values, without modifying your request parameters each time.

Use this feature to test APIs with dynamic inputs, such as running the same workflow for multiple users, IDs, or configurations.

​

Using a Data File in Collection Runner

Follow these steps to run a collection with custom data:

1. Open Collection Runner

   In the Collections sidebar, find the collection you want to execute and click the Run icon next to it.

   
2. Select a Data File

   In the Runner configuration panel, click Select Data File.

   Supports JSON & CSV files (max 100MB)

   

   Once added, Requestly will automatically detect the file type and preview its structure.

3. Preview Data and Map Variables

   After selecting the file, a preview of your data will appear.

   • For CSV files: verify column names and types
   • For JSON files: check object keys and structure

   Each key or column name should match the variable used in your requests, such as {{storyId}}.

   
4. Start the Run

   Click Save and then Start Run.
   The Collection Runner will replace variables with data from your file for each iteration.

   

​

How Data Files Work

When you attach a CSV or JSON file to your manual run:

• Each row (CSV) or object (JSON) represents one iteration
• Variables inside your requests (like {{storyId}}) will be replaced with the corresponding values
• Requestly automatically cycles through each data set until all iterations are complete

​

Supported File Formats

​

CSV Format

• The first row defines variable names
• Each subsequent row represents one iteration
• Each row must have the same number of columns

Example:

city,temperature  
Vancouver,10  
Austin,24  
London,12

​

JSON Format

• Must be an array of key-value objects
• Each object defines one iteration
• A value can be text, a number, a boolean, null, a nested object or an array

Example:

[  
  { "city": "Vancouver", "temperature": 10 },  
  { "city": "Austin", "temperature": 24 },  
  { "city": "London", "temperature": 12 }  
]

​

Nested values in JSON

A value in a JSON file can be a nested object or an array:

[
  { "user": { "name": "Ada" }, "tags": ["a", "b"] }
]

• In a request, {{name}} becomes an object’s or an array’s JSON text. With this file, {{user}} becomes {"name":"Ada"} and {{tags}} becomes ["a","b"]. A null value becomes empty text.
• In a script, rq.iterationData returns the value as it is written: rq.iterationData.get("user").name is "Ada", and rq.iterationData.get("tags") is the array ["a", "b"].

​

Example Use Case

For a request like

GET https://api.example.com/weather?city={{city}}

and a data file containing

city
Vancouver
Austin
London

Requestly will automatically replace {{city}} with each value during the run.

​

Accessing Data in Scripts

You can access data file values programmatically in your pre-request and post-response scripts using the rq.iterationData object. This allows you to implement conditional logic, validate responses, or perform calculations based on the input data.

Example:

// Pre-request script
const city = rq.iterationData.get("city");
console.log(`Testing weather API for: ${city}`);

// Post-response script
const expectedCity = rq.iterationData.get("city");
const responseData = rq.response.json();

rq.test("Response contains correct city", function() {
    rq.expect(responseData.city).to.equal(expectedCity);
});