Branching and Looping in Postman

Last Updated : 9 Sep, 2026

Branching and looping help control the execution flow of API requests during a Postman collection run. They allow requests to execute in a custom order or repeat based on specific conditions.

  • Branching directs execution to different requests based on a condition.
  • Looping repeats a request or workflow until a condition is met.
  • Both are useful for creating dynamic API workflows and automated tests.

Understanding pm.execution.setNextRequest()

pm.execution.setNextRequest() is a Postman scripting method used to specify which request should execute next during a collection run. It allows you to override the default request order and create custom request workflows.

pm.execution.setNextRequest("Request Name");

  • The argument can contain the request name or request ID.
  • The method can be used in a request's Pre-request Script or Post-response script.
  • It takes effect when the collection is run through the Collection Runner, Postman CLI, or Newman and has no effect when an individual request is sent using Send.
  • The request execution order in the collection itself is not permanently changed.
  • If the method is assigned multiple values during script execution, the last value takes precedence.

Implementing Branching in Postman

Branching allows a collection to follow different request paths based on a condition. The condition can use response data, status codes, variables, or other script logic.

if (pm.response.code === 200) {
pm.execution.setNextRequest("Get User");
} else {
pm.execution.setNextRequest("Handle Error");
}

  • A successful response directs the workflow to Get User.
  • An unsuccessful response directs it to Handle Error.
  • The selected request must be within the scope of the collection run.

Implementing Looping in Postman

Looping allows Postman to execute the same request repeatedly during a collection run. Passing the current request to pm.execution.setNextRequest() sends execution back to that request.

For example, the following post-response script runs the current request three times:

var count = !pm.variables.get("count")
? 1
: Number(pm.variables.get("count"));

if (count < 3) {
pm.variables.set("count", count + 1);
pm.execution.setNextRequest(pm.execution.location.current);
} else {
pm.variables.unset("count");
pm.execution.setNextRequest(null);
}

  • pm.execution.location.current identifies the current request.
  • The counter determines how many times the request is repeated.
  • The example runs the request three times before stopping.
  • A termination condition should always be included to prevent indefinite looping

Controlling Loop Execution

A loop should have a clear condition for continuing and stopping. The condition can be based on an iteration count, response value, variable, or another requirement.

Example:

if (count < 3) {
pm.execution.setNextRequest(pm.execution.location.current);
} else {
pm.execution.setNextRequest(null);
}

  • When the condition is true, the current request runs again.
  • When the condition becomes false, the workflow stops.
  • A termination condition prevents an infinite loop.

Stopping Request Execution

To stop a collection workflow after the current request completes, pass null to pm.execution.setNextRequest()

pm.execution.setNextRequest(null);

For example, a workflow can stop when an API returns an unsuccessful response:

if (pm.response.code !== 200) {
pm.execution.setNextRequest(null);
}

  • null prevents another request from being selected.
  • The current request finishes before the collection run stops.
  • When a collection run has multiple configured iterations, this also stops each iteration after the current request.

Note:pm.execution.skipRequest() is different from pm.execution.setNextRequest(null). skipRequest() is used to skip a request, while setNextRequest(null) stops the workflow.

Request Execution Scope

The scope of pm.execution.setNextRequest() depends on what you are running.

  • Entire collection: Any request in the collection can be selected as the next request, including requests inside folders.
  • Folder: The next request must belong to the same folder.
  • Individual request: The method has no effect when the request is sent directly using Send.
  • Collection execution: The method works with collection execution through the Collection Runner, Postman CLI, or Newman.

Using Request Names and IDs

pm.execution.setNextRequest() accepts either a request name or request ID.

pm.execution.setNextRequest("Get User");

We can also use a request ID:

pm.execution.setNextRequest("1ab12345-4ab4-4124-c000-12341abc1234");

  • Request names are easier to read and maintain when names remain stable.
  • Request IDs remain unchanged when the request name is changed, making IDs useful for stable references.
  • Use pm.info.requestId to obtain the ID of the currently executing request.

Best Practices

Following best practices helps keep branching and looping workflows clear, reliable, and easy to maintain in Postman.

  • Define a termination condition for every loop.
  • Use request IDs when a stable request reference is important.
  • Keep branching conditions clear and easy to understand.
  • Use meaningful request names for readable workflows.
  • Avoid unnecessary loops and branches when the default collection order is sufficient.
  • Test every execution path to ensure each branch and termination condition behaves as expected.
  • Remember that setNextRequest() controls collection-run execution; it does not permanently reorder the collection.
Comment

Explore