Use a dataset with a monitor

You can use a Postman dataset and its views as iteration data for a monitor run. Every row returned by the selected view becomes one collection iteration, available through pm.iterationData. Datasets are shared across workflows, so the same data can power collection runs, code mocks, and monitors without duplication. Because a monitor resolves the current dataset view each time it runs, scheduled tests can use the latest data without re-uploading files. To access local data files or external data sources with a monitor, you must use a Private API Monitoring runner.

Prepare your collection

Add variables to the requests in your collection. Variable names should match the field names exposed by the view you select. For example, if your view includes a userId field, reference it as {{userId}} in a request URL. Create a dataset with at least one view that returns the data you want to use.

During a monitor run, the view’s field values are also available in pre-request and post-response scripts through pm.iterationData. Learn more about using iteration data variables in scripts.

1
const token = pm.iterationData.get('token');
2
pm.request.headers.upsert({
3
    key: 'Authorization',
4
    value: `Bearer ${token}`
5
});

You can also use the pm.datasets function to run saved views or run read-only SQL queries in scripts while a monitor is running. Learn more at Manage and use datasets in scripts.

Use a dataset with a monitor

When you configure a monitor, you can select a dataset view to provide iteration data for the monitor run. You must use Private API Monitoring runners to access local data files or external data sources.

To select a dataset when configuring a monitor, do the following:

1. Create or edit a monitor.

2. Under Iteration data, click the dropdown list and select a dataset view. Optionally, click New dataset to create one without leaving the monitor configuration.

   A preview of the dataset view appears in the right pane. From here, you can do the following:

   • Edit the view and click Run to preview the results.
   • Click Save to save your changes to the view.
   • Click Set as new view to save the changes as a separate view. The monitor automatically switches to the new view.
   • Click Reset to discard changes and return to the original view.

3. Select an Iteration strategy for the run. Learn more about iteration strategies.

4. Enter the number of iterations. Not available for the Default iteration strategy.

5. Complete the remaining monitor configuration and save the monitor.

Iteration strategies

An iteration strategy determines what happens when the number of configured iterations differs from the number of rows returned by the selected view.

• Default — The monitor runs one iteration for each row returned by the view.
• Round robin — If iterations exceed the number of rows, the monitor starts again from the first row for the remaining iterations.
• Repeat last — If iterations exceed the number of rows, the monitor reuses the last row for the remaining iterations.
• Stop at end — The monitor stops when it runs out of rows, regardless of the configured number of iterations.