Customize request order in a collection run

By default, when you run a collection, Postman runs all requests in the order they appear in your collection. Requests in folders run first, followed by requests in the root of the collection. To dynamically change the order of requests during a collection run, use the pm.execution.setNextRequest() function.

Instead of manually changing the order of requests each time you start a collection run, you can automate this behavior. Add pm.execution.setNextRequest() to your scripts to specify which request Postman runs next, following the current request. With this function, you can build workflows that chain requests, running them one after the other in a custom order.

Setting the next request

Set the next request

To specify the request to run next, add the following code on the Scripts > Post-response tab of a request. Replace request_name with the name of the request you want to run next.

pm.execution.setNextRequest("request_name");

Postman runs the specified request after completing the current request.

Loop over a request

If you pass the name of the current request to the setNextRequest function, Postman will run the current request repeatedly.

Looping over a request

Important: To prevent the request from looping indefinitely, wrap setNextRequest in extra logic. For example, you can set the request to exit the loop after a certain number of iterations or when another condition is met. Otherwise, to end the loop, you can force close the Collection Runner.

Stop a workflow

To stop a workflow, add the following code on the Scripts > Post-response tab of a request:

pm.execution.setNextRequest(null);

The collection run will stop after Postman completes the current request.

You can also skip the execution of a request from the Scripts > Pre-request tab using the pm.execution.skipRequest method. Learn more about skipping request execution from pre-request scripts.

Tips for building request workflows

Keep the following tips in mind when using the pm.execution.setNextRequest() function.

Use setNextRequest() when you run an entire collection

Use the pm.execution.setNextRequest() function when running a collection with the Collection Runner, the Postman CLI, or Newman. It has no effect when you run a request using Send.

Use setNextRequest() in pre-request or post-response scripts

You can use pm.execution.setNextRequest() in the pre-request script or the post-response script of a request. If more than one value is assigned, the last value that's set takes precedence.

Specify the next request using the request ID

A request's name may change, but changing its name doesn't change its ID. For this reason, it's best to use the request ID when you specify the next request.

To get the request ID, use pm.info.requestId. For example, run console.log(pm.info.requestId). To learn more, see Script Workflows.

You can also get the request ID in Postman. Open the request and, from the right sidebar, select information Information icon. The request ID is prepended with your user ID (the first block of characters). Copy the request ID. For example, if the ID is 33664548-8de70c53-3f37-4570-a066-d1171451d11e, copy 8de70c53-3f37-4570-a066-d1171451d11e.

setNextRequest() always runs last

The pm.execution.setNextRequest() function always runs at the end of the current request. If you put other code blocks anywhere in the pre-request script or post-response script after this function, the code blocks will still run before pm.execution.setNextRequest().

setNextRequest() scope is limited to the collection

The scope of pm.execution.setNextRequest() is the source of your collection run.

  • If you run an entire collection, you can set any request in the collection as the next request, even requests inside folders.
  • If you run a folder, the scope of pm.execution.setNextRequest() is limited to that folder. In this case, you can set any request in the same folder as the next request, but not requests located in other folders or at the root of the collection.

Learn more about running collections or folders.

Next steps

After learning about how to build request workflows, you can write some scripts.

Last modified: 2024/09/10