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, validate API responses in scripts, and reference datasets, sources, and views by ID in your requests and Flows. Datasets enable you to reuse the same data across workflows and work with consistent, queryable data instead of duplicating or hardcoding values.

Datasets can be backed by local or cloud data files or live data sources such as databases. Views enable you to filter, transform, and subset that data for specific scenarios. This enables you to test against current data, target specific test cases, and control the data used by collection runs, scripts, and mock servers.

Example dataset

In the following examples, assume you have a dataset named users-dataset with a local CSV file data source that includes userId, email, and name fields:

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

Use datasets in collection runs

You can use datasets as iteration data when manually running a collection. Each row returned by the selected view becomes an iteration in the collection run, allowing the same requests to run with different inputs. Views enable you to control which data is used during a run, such as filtering a large dataset to a specific set of test scenarios.

You can also use datasets with monitors and performance tests.

To run a collection with a dataset, see Use a dataset with a collection run. That page covers selecting a dataset and view, controlling how many iterations run, and accessing iteration data in your requests and scripts.

Query the dataset in scripts

During a collection run or monitor run, you can use the pm.datasets function in pre-request and post-response scripts to query the dataset using values from the current iteration. This is useful when you need data beyond what the selected view exposes as iteration variables. Query results return rows as an async iterable, so use the for await...of loop to read the returned rows. You can also use executeView() to validate responses against a predefined view instead of writing a custom query in the script. Learn more about using datasets in scripts.

const ds = pm.datasets("users-dataset-id");
const result = await ds.executeQuery(
  "SELECT * FROM users WHERE email = ?",
  [pm.iterationData.get("email")]
);
const allRows = [];
for await (const row of result.rows) {
  allRows.push(row);
}
console.log(JSON.stringify(allRows));

Use dataset variables in scripts

You can reference a dataset, source, or view anywhere in a request. This includes the base URL, auth, path parameters, headers, and body. Use the {{variable}} syntax, where variable is the name of the entity. For example, you can enter {{users-dataset}} as a path parameter in your request URL GET /users/{{users-dataset}}. Postman resolves the variable to the entity’s ID when the request runs, so you can access it in a script without hardcoding the ID.

const datasetId = // Get dataset Id from url/headers/other
const ds = pm.datasets(datasetId);
const result = await ds.executeQuery(
  "SELECT * FROM users WHERE email = ?",
  [pm.iterationData.get("email")]
);
const allRows = [];
for await (const row of result.rows) {
  allRows.push(row);
}
console.log(JSON.stringify(allRows));

Use datasets in mocks

You can use the pm.datasets function in a mock 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 mock:

1. In your mock implementation file, load the dataset using pm.datasets().

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

   const http = require("http");
   const url = require("url");
   const PORT = process.env.PORT || 4500;
   const server = http.createServer(async (req, res) => {
     const { method } = req;
     const { pathname, query } = url.parse(req.url, true);
     // @endpoint GET /user
     if (method === "GET" && pathname === "/user") {
       const ds = pm.datasets("users-dataset-id");
       const result = await ds.executeQuery(
         "SELECT userId, email, name FROM users WHERE userId = ?",
         [query.userId]
       );
       const allRows = [];
       for await (const row of result.rows) {
         allRows.push(row);
       }
       if (allRows.length === 0) {
         res.writeHead(404, { "Content-Type": "application/json" });
         return res.end(JSON.stringify({ error: "User not found" }));
       }
       res.writeHead(200, { "Content-Type": "application/json" });
       return res.end(JSON.stringify(allRows[0]));
     }
     res.writeHead(404, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "Endpoint not defined" }));
   });
   server.listen(PORT, () => {
     console.log(`Mock server running on port ${PORT}`);
   });

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

   http://localhost:4500/user?userId=2

The mock queries the dataset when the request runs and returns the matching data in the response. Query results return rows as an async iterable, so use the for await...of loop to read the returned rows. You can also use views with executeView() to reuse predefined queries across endpoints.

Learn more about mocks and using datasets in scripts.

Use datasets in scripts

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

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

1. Send a request to an endpoint that returns user data, such as:

   GET /user?userId=2

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

   const ds = pm.datasets("users-dataset-id");
   const responseJson = pm.response.json();
   const result = await ds.executeQuery(
     "SELECT userId, email, name FROM users WHERE userId = ?",
     [responseJson.userId]
   );
   const allRows = [];
   for await (const row of result.rows) {
     allRows.push(row);
   }
   pm.test("Response matches dataset", function () {
     pm.expect(allRows.length).to.eql(1);
     pm.expect(responseJson.email).to.eql(allRows[0].email);
     pm.expect(responseJson.name).to.eql(allRows[0].name);
   });

3. Click Send.

When the request runs, the script queries the dataset and compares the response data with the matching row. Query results return rows as an async iterable, so use the for await...of loop to read the returned rows. 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 pre-request scripts and post-response scripts, and using datasets in scripts.