Use datasets in Postman

After you create a dataset, you can use it across your API workflows in Postman. You can run data-driven collection tests, power dynamic mock server responses, and validate API responses in scripts. Datasets enable you to reuse the same data across workflows and work with consistent, queryable data instead of duplicating or hardcoding values.

Use datasets in collection runs

You can use datasets as iteration data when manually running a collection. The data is organized into fields (columns) you can reference in your requests using variables. Each row is used to run your requests with different inputs. The number of iterations is determined by the number of rows returned by the selected view.

Use the following example to use datasets in your collection runs:

1. Create a dataset with a local file data source that includes userId, email, and name fields in CSV format.

   1
   userId,email,name
   2
   1,user1@example.com,User One
   3
   2,user2@example.com,User Two
   4
   3,user3@example.com,User Three
   5
   4,user4@example.com,User Four

2. Click Items in the sidebar.

3. Click Collections and select the collection you want to run against the dataset.

4. Reference the fields in your requests using variables that match the field names in your dataset.

   1
   GET /users?userId={{userId}}&email={{email}}&name={{name}}

5. Select the collection again and click Run in the upper right.

6. Select Run manually.

7. Configure the collection run settings as needed, such as the delay.

8. Under Dataset, select the dataset you’d like to use for the run. Then select a view with the data you want to run against.

   You can click Create a new dataset or Create a new view to create and select a dataset or view without leaving the collection run configuration.

9. (Optional) Click the Data tab in the left pane to preview and edit the view you selected.

10. Click Start run.

During the run, Postman assigns values from each row to your variables, so each request runs with a different set of data. You can also view the data used for each iteration in the collection run summary.

Learn more about using variables and manually running collections.

Use datasets in mock servers

You can use the pm.datasets function in a local mock server to return dynamic responses based on queryable data. This enables you to use the same dataset across requests, filter data for specific endpoints, and simulate more realistic API behavior instead of returning only static responses.

Use the following example to use a dataset in a local mock server:

1. Create a dataset with a local file data source that includes userId, email, and name fields in CSV format.

   1
   userId,email,name
   2
   1,user1@example.com,User One
   3
   2,user2@example.com,User Two
   4
   3,user3@example.com,User Three
   5
   4,user4@example.com,User Four

2. In your local mock server implementation file, load the dataset using pm.datasets().

3. Run a query against the dataset in your request handler and return the matching row in the response.

   1
   const http = require("http");
   2
   const url = require("url");
   3
   const PORT = process.env.PORT || 4500;
   4
   5
   const server = http.createServer(async (req, res) => {
   6
     const { method } = req;
   7
     const { pathname, query } = url.parse(req.url, true);
   8
   9
     // @endpoint GET /users
   10
     if (method === "GET" && pathname === "/users") {
   11
       const ds = pm.datasets("users-dataset-id");
   12
   13
       const result = await ds.executeQuery(
   14
         "SELECT userId, email, name FROM users WHERE userId = ?",
   15
         [query.userId]
   16
       );
   17
   18
       if (result.rows.length === 0) {
   19
         res.writeHead(404, { "Content-Type": "application/json" });
   20
         return res.end(JSON.stringify({ error: "User not found" }));
   21
       }
   22
   23
       res.writeHead(200, { "Content-Type": "application/json" });
   24
       return res.end(JSON.stringify(result.rows[0]));
   25
     }
   26
   27
     res.writeHead(404, { "Content-Type": "application/json" });
   28
     res.end(JSON.stringify({ error: "Endpoint not defined" }));
   29
   });
   30
   31
   server.listen(PORT, () => {
   32
     console.log(`Mock server running on port ${PORT}`);
   33
   });

4. Start the mock server and send a request to the endpoint. For example, you can send a GET request to the following:

   1
   http://localhost:4500/users?userId=2

The mock server queries the dataset at runtime and returns the matching data in the response. You can also use views with executeView() to reuse predefined queries across endpoints.

Learn more about local mock servers and managing and using datasets in scripts.

Use datasets in scripts

You can use the pm.datasets function in post-response scripts to validate response data against queryable data stored in a dataset. This enables you to compare API responses with expected values, test multiple scenarios, and reuse the same data across requests and workflows.

Use the following example to use a dataset in a post-response script:

1. Create a dataset with a local file data source that includes userId, email, and name fields in CSV format.

   1
   userId,email,name
   2
   1,user1@example.com,User One
   3
   2,user2@example.com,User Two
   4
   3,user3@example.com,User Three
   5
   4,user4@example.com,User Four

2. Send a request that returns user data, such as:

   1
   GET /users?userId=2

3. In the request’s Scripts > Post-response tab, load the dataset and query it using a value from the response.

   1
   const ds = pm.datasets("users-dataset-id");
   2
   const responseJson = pm.response.json();
   3
   4
   pm.test("Response matches dataset", async function () {
   5
     const result = await ds.executeQuery(
   6
       "SELECT userId, email, name FROM users WHERE userId = ?",
   7
       [responseJson.userId]
   8
     );
   9
   10
     pm.expect(result.rows.length).to.eql(1);
   11
     pm.expect(responseJson.email).to.eql(result.rows[0].email);
   12
     pm.expect(responseJson.name).to.eql(result.rows[0].name);
   13
   });

When the request runs, the script queries the dataset at runtime and compares the response data with the matching row. You can also use executeView() to validate responses against a predefined view instead of writing a custom query in the script.

Learn more about writing post-response scripts and managing and using datasets in scripts.