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.

UPDATE: Check out the follow up: Looping through a data file in the Postman Collection Runner ?

Author: Abhinav

CEO @ Postman

51 thoughts on “Using CSV and JSON data files in the Postman Collection Runner”

  1. 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?

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

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

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

    1. 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.

  3. 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?

    1. 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.

      1. 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.

  4. 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}}”


    1. 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.

      1. 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:


        1. 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}}.

  5. Doesn’t seem to work with nested elements:

    “parent” : [{child : “{{PARAM}}”}],

    Data is not subbed out in my POST request

    1. 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.

  6. 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?

  7. 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?

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

      1. 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.

  8. 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 ‘

  9. 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

  10. 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.

  11. 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?

  12. Hi,

    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

  13. 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!

  14. “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.”

  15. 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 ?

  16. 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 ?

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

  18. Hi,

    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.

    1. 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.

  19. 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.

  20. 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.

  21. Hello,
    I am trying to extract a column with multiple values from excel to an array in postman.
    Is there a way I can do this without using Iteration?
    Thank you,

Comments are closed.