Use datasets in Postman

Beta

Datasets are available on Postman Solo, Team, and Enterprise plans. For more information, see the pricing page.

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

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

Click Items in the sidebar.
Click Collections and select the collection you want to run against the dataset.
Reference the fields in your requests. See Use iteration data in requests, Use iteration data in scripts, Query the dataset in scripts, and Use dataset variables in scripts for different ways to use dataset data.
Select the collection again and click Run in the upper right.
Select Functional, then select Local.
Configure the collection run as needed.
Click the Test data dropdown list and select the Datasets tab.
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.
(Optional) Click the Data tab in the left pane to preview the view you selected.
Click Start run.

The collection run summary shows the data used for each iteration.

Use iteration data in requests

Dataset fields are automatically exposed as variables during the run. You can access them using the {{variable}} syntax. For example, if your dataset has a userId field, you can reference it in your request URL as {{userId}}. Learn more about using variables.

GET /user?userId={{userId}}&email={{email}}&name={{name}}

Use iteration data in scripts

You can access the values from the current iteration in pre-request and post-response scripts using pm.iterationData. Learn more about using iteration data variables in scripts.

console.log(pm.iterationData.get("email"));

Query the dataset in scripts

During a collection 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 code mocks

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

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

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}`);
});

Start the code 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 code 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 enables you to compare API responses with expected values, test multiple scenarios, and reuse the same data across requests and workflows.

To learn how to use datasets in scripts during a collection run, see Use datasets in collection runs.

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

Send a request to an endpoint that returns user data, such as:
```
GET /user?userId=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);
});

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.