Using CSV and JSON data files in the Postman Collection Runner

Postman’s Collection Runner is a powerful tool. As its name implies, the Collection Runner (CR) lets you run all requests inside a Postman collection one or more times. It also executes tests and generates reports so you can see how your API tests compare to previous runs.

Basic usage
To run a collection, open the Collection Runner window by clicking on the link in the navigation bar. Choose a collection from the drop down menu, and hit Start.

Screen Shot 2016-06-25 at 13.07.25

That's all it takes!

To run a collection multiple times, you need to set the iteration count.
Screen Shot 2016-06-25 at 13.07.52

One feature that gets most people stumped is using data files with the Collection Runner. On this front, we admit that the Postman documentation lacks clarity and I hope that this article helps you understand the feature better.

The Collection Runner let’s you import a CSV or a JSON file and then use the values from the data file inside HTTP requests and scripts. We call these variables data variables. To use them inside the Postman UI, you have to follow the same syntax as environment or global variables. Having the same syntax helps you test individual requests inside Postman using dummy environment values. When you move to the Collection Runner you don't have to change anything.

Data variables in requests
Variables inside the Postman UI are enclosed inside curly braces. For example, in the screenshot below, {{username}} and {{password}} inside URL parameters would be replaced by corresponding values from the data file:

Screen Shot 2016-06-25 at 14.47.47

Data variables in pre-request and test scripts
Inside pre-request and test scripts, the special data dictionary contains values loaded from the data file for a specific iteration. For example data.username or data[‘username’] would let you access the value of the username variable from a data file.

Screen Shot 2016-06-25 at 14.48.35

CSV files
For CSV files to work inside the Collection Runner, the first row needs to consist of variable names that you want to use inside requests. Every subsequent row is used as a data row. Make sure the line endings of the CSV file are in the Unix format. That's a restriction in our current CSV parser. Line endings can be changed in a text editor like Sublime Text.

Download sample CSV file

To see how the CSV file values are mapped to a Postman request, check out this illustration:


JSON files
The JSON file needs to be an array of key/value pairs. The keys are used as variable names while the values are replaced inside requests.

Download sample JSON file

To see how the JSON file values are mapped to a Postman request, check out this illustration:

We have created a sample collection for you using our service as an example.

  1. Click on the Import collection button in the collection sidebar.

Screen Shot 2016-06-25 at 15.08.35

  1. Copy and paste the link given below in the Import from a URL input field and press Import.

  1. Once the collection is imported, have a look at the first request.

Screen Shot 2016-06-25 at 15.09.38

The request uses the username variable as a URL parameter.

  1. Open the test script editor. It’ll show you the following snippet:

tests["Body contains username"] = responseBody.has(data.username);
tests["Body contains password"] = responseBody.has(data.password);

The test checks for the presence of the username and password values from the data file in the responseBody variable. If everything works properly, then this test should pass.

  1. Open the Collection Runner window and select the “Walkthrough – Data files” collection.

Download either of the files linked below.



  1. Select “Choose files” from the file and load the data file in the collection runner. If the data file was loaded successfully, you can preview the values within the Collection Runner.

Screen Shot 2016-06-25 at 15.10.55

  1. The iteration count can be anything from 1 to 3. If the number of iterations specified is less than the values in the data file, then the last row values are repeated.

  2. Run the collection and observe the result. If everything went well, you should see all tests passing in the Collection Runner result window.

Screen Shot 2016-06-25 at 15.11.32


Testing your API using the Collection Runner and data files would make it more robust by testing for hundreds of variations instead of a couple of use cases. It can also be used for performing basic operations like database initialization, clean up or just for a basic checkup. If you have come up with a creative use case for using data files inside Postman, let us know in the comments and we will feature it on the blog.

  • Nix

    I have an environment variable called "counter", which basically increments every time I create an object. How can I use that environment variable so I don't have to create 10 sets of data in my JSON/CSV to create 10 objects?

    • Postman REST Client

      I did not get your question exactly. Are you trying to generate data dynamically?

      • Ariel Segura

        Hi, i'm exactly trying to generate my post and put bodies dynamically through a csv – without succeed. Does postman support that?

        • Sebastien Auroux

          Does postman support that?

    • Harish Sona

      in the tests tab fetch the counter and increment it and set it back to counter
      let value= Number(pm.environment.get('your_key'));

  • YYx

    How to parse the zip compressed package in the Test editor

  • dhimas

    If there is 10 times the GET request. Can I know which request the best and worst request?

  • Tucker Brennan

    Is there any way to have the variable actually within the URL instead of as a parameter? This works with the Environment variables but I can't seem to get it to work with the URL itself. IE:{{id}} will not work but{{id}} does. any thoughts?

    • Postman REST Client

      Variables are replaced for the entire URL. Not sure why you are facing the issue Tucker. Can you email a sample collection to us at

  • Appreciate this post. Let me try it out.

    Also visit my blog post – brave frontier mod

  • hello as a matter of fact your ideas regarding How to use CSV and JSON data files in Postman for comprehensive API testing Especially, your awesome post on this page are contemplated as a critical Issue

  • tareq shaw

    how to get raw data posted by postman in php file

  • Sarfaraz Ahmad

    Is there any way to reset the values of environment variables before running the collection runner?

    • Jeremy Noel

      I know I am a little late to this discussion, but you can use postman.clearEnvironmentVariable(name); to clear any of them out. I created an array of the variable names I needed to clean, and looped through it as part of the test of the final element.

      function cleanup(){
      var clean = ["x", "y", "z", ];
      for(var i = 0; i < clean.length; ++i){

      The con? Its not terribly dynamic, you have to create the array of variable names yourself. Additionally, I am not certain whether it affects the time displayed for test results, however I would expect Postman to isolate the test time from the actual ReST service timing.

  • Tim Williams

    When I'm outside the collection runner, and just want to run my request in the normal UI, would I set up an evironment variable for each "data" variable? That would seem to imply a lot of duplication?

    For example in my collection I might have {{url}}/action?id={{id}} and have url and id defined as environment variables. Then defined again in my data variables. Is that the correct approach?

    • Nate Jackson

      The only approach I've gotten to work for having things work in Postman *and* Collection Runner against a data file is to:

      1) set up a global variable in the pre-request script:

      postman.setGlobalVariable("expectedunitcost", 77.175);

      2) in my test, compare a value against the data object(or the globals object if the data object is null)

      var payload = JSON.parse(responseBody);
      tests["unitPrice is accurate"] = payload.laborPrice.unitPrice === data["expectedunitcost"] || globals["expectedunitcost"];

      This assumes a value named expectedunitcost exists in your Collection Runner data file.

      • Tim Williams

        Thanks Nate, unfortunately that still leads to duplication – you need data variables declared in your pre-request script, and conditional statements throughout your tests, as well as data files for the collection runner.

        Ideally within Postman you would be able to specify a data file, just as you can in the collection runner.

  • tothefuture

    I am trying to post an integer value from a .json file. This will be a test POST request, the column should not accept the integer value, and a test will run to verify that.

    However in the raw body of the parameterized POST request the only way to call the variable is in double quotes. So, it always tries to post this integer variable as a string since it is in double quotes, causing my tests to fail. Is there some workaround for this?

    example json file to be used by the collection


    "id_value" : 1


    Example POST request using data variables


    "id" : "{{id_value}}"


    • Preet

      Did you get this sorted? I am having the same problem where the variables are of mixed types. Booleans and integers are coming out as strings.

      • tothefuture

        Yeah, you have to include the attribute name in the variable.

        So in the data/environment file your variable value would be:

        "id_value" : ""id":1"

        Then in the raw json payload you would call the variable without quotes:


        • Amanda Bouman

          Do you have an example where this worked? Collection Runner and Newman both don't seem to recognize the double brackets (without quotes) as needing to be replaced and my request literally sends {{id_value}}.

  • Sam McDonald

    Doesn't seem to work with nested elements:

    "parent" : [{child : "{{PARAM}}"}],

    Data is not subbed out in my POST request

    • pjohnkeane

      Did you ever find a way around this?

    • tothefuture

      You can work around this by including the attribute names in the variable.

      So in the data/environment file your variable value would be:


      "PARAM" : ""parent" : [{ "child_name" : "child_value" }]"


      Then in the raw json payload you would call the variable without quotes:




      POSTman will display a syntax error, but this can be ignored.

  • Srinivas Kalyan

    I am using the env_gk as environmental variable and using that for maintaining the base url.

    URL: {env_gk}}/api/v1/{{users}}?includePermissions=true.

    users is another global variable which is set like this in pre-request script.

    postman.setGlobalVariable("users", 'users/'+data.user);

    will it work? the final out come should be users-> users/user_id and user_id will be from data file.

    Also is there a way to check how URL resolved?

  • Srinivas Kalyan

    can i choose DB as data source from postman?

  • Pingback: API integrations using Postman – Building a Slack channel bot – Postman Blog()

  • Prasad

    I am trying iteration variable. But it always runs only once.

    Have uploaded the data file as csv with two records and a header row. If i specify the iteration value anything greater than 1 , it always executes only once.

    It just reads the first record from the file, am i missing anything?

    • abhijitkane

      @disqus_SV6ALCBuTj:disqus Can you try upgrading to v4.1.2 of the app? chrome://extensions > Enable 'developer mode' > Update.

      • Prasad

        My Postman app is on that version.
        Postman 4.1.2

        Under my collections folder i have 3 apis chained. When i give iteration 1 it gets executed once. When i give a number 4 it gets executed twice and if 7 thrice and there on.. Is that how its supposed to work.

  • Prasad

    Using collection runner and feeding the data file in csv formart.

    In my pre-request script i have

    "merchantId", data.merchantId

    Here is the preview of data
    iteration merchantId
    1 abc
    2 xyz

    It gets executed during first iteration , but while second iteration starts, its errors out saying

    'Something is wrong with your test scripts. Please fix them in the editor first.
    Message : There was an error during JSON.parse(); Unexpected token E '

  • Madhu CS

    Is there a way to export/write data to external CSV file ?

  • Stéphane Moser

    Is there a way to set "Authorization" header by using a CSV / JSON file. I do not want to store the credentials, even if encoded in base64 within the collections. I want to have those credentials stored externally.

    I've tried to set it this way (CSV/JSON) but I got an error. I've also tried to use "Preset" and then use "Run", but when I download the collection, I can see that the credentials are embedded in the file.

    Also note that I do not want to store the credentials as an environment variable, because I will export environment variables after the test run.

    How could I do such thing?

    Thank you in advance for your answer. Stéphane

  • Ashish

    hi,we provide online training & video tutorial for soapui

    for free videos refer

  • Kabir

    var jsonData = JSON.parse(responseBody);
    tests["Your test name"] = jsonData.value === 100;

    In value do I have to provide the complete JSON path? When I provide the path, it's failing test.

  • Anurag Bhalla

    I need to test a bunch to servers each with a bunch of URLs. My list of servers and the url list keeps on changing. Is there a way I automate looping through these two data sets?

  • Ganesh


    I tried using the tool. I am facing issue with Json String values. Even the demo link run given with sample Json is failing.

    My Sample Json looks like this
    "4":"TEST SALE PRICE66",

    "Type" : "Sale",
    "active" : true,
    "Entity" : {
    "id" : {{1}},
    "code" : {{2}},
    "elementType" : "Legal_Entity"
    "code" : {{3}},
    "description" : {{4}},
    "currency" : {
    "id" : {{5}},
    "code" : {{6}}

    But my REST API is getting the string values with single Quotes and giving error. Any hint as what the issue and possible solution

  • chris

    Hi – I have expected results in my imported .csv file that include ®.
    The postman .csv data file reader during the reading (and previewing) process for Collection Runner seems to interpret these as � This is causing false fails in my test results. Note that I confirmed my csv file is saving these characters correctly as ®, and I also confirmed that using postman console.log("SP Complete®"); returns as ®. The problem seems to be in the postman csv reader. Please advise if there is a way around this or a fix coming soon. Thx!

  • David A Hollema

    "If the number of iterations specified is less than the values in the data file, then the last row values are repeated."

    Shouldn't this read, ""If the number of iterations specified is GREATER than the values in the data file, then the last row values are repeated."

  • Ravi

    We have to supply data file path for every run in collection Runner. Is there a way to set data file path once and run anytime ?

  • Ravi

    Another question : ActiveXObject was not supported by Chrome browser, thats why we cannot establish DB connection from Postman(Chrome extension version). Now we got stand alone Windows/Mac App. Is there a way to connect database in recent Windows/Mac App ?

    • Dan

      Hi Ravi,

      Did you find a way to do this?

  • Abhishek

    Doesnt work me.
    the request does not replace {{paramname}} with the json input I am sending.
    Even the samples dont run

  • Gaurav


    Thanks for this article.
    I have imported the demo collection using mentioned link however on run getting "404
    Not Found" error.

    Tried both csv & json files. in preview its showing correct data.

    However on run getting error.

    Any suggestion.

    • Gaurav


      I have created copy of data file with only 3 parameters url, username, password
      url as

      Request link is also modified to{{username}}&password={{password}}&url={{url}}

      Now results are getting passed.

    • Anderson

      Thanks for getting in touch. I think your best bet would be to join our Slack community and post your question there, here is a link to join: It's a great resource for all Postman users, you'll even find our very own devs on there all the time. Let me know how you get on.


    Need to run a collection from console. My collection contains multiple requests where each request has there own json/csv testdata. i'm able to run each of them from runner individually. Is there a way where i can run whole collection with each request having their own testdata file from runner/console.

    • Vismay Patel

      You can export the collection and run it using wingman.

  • Nadier Isaacs

    Hi, thanks for sharing this great article.
    Is there anyway to run an individual Post / Get request using a csv file?
    This would be useful when testing individual requests before committing them to the collection.