Persist state across requests in local mock servers

The pm.state object provides a persistent store for your local mock server. You can read, write, and update data across requests, enabling your mock to behave like a real service instead of returning static responses. State is shared and persists beyond a single run until it’s cleared using pm.state.clear(). All methods are asynchronous and return Promises, so use await to access their results.

pm.state

Use the pm.state object to persist and manage data across requests in your local mock server.

pm.state.get(key:String)

Retrieves the value stored for the key in the current mock session. Resolves to the value if found or undefined if the key doesn’t exist. Use this to read session data and make decisions based on it.

1
const user = await pm.state.get("user");
2
3
if (user) {
4
  return { status: 200, body: user };
5
}
6
7
return { status: 404, body: { error: "User not found" } };

pm.state.set(key:String, value:Any)

Stores a JSON-serializable value under the key for the current mock session. Use this to create or replace session state.

1
await pm.state.set("user", {
2
  id: "123",
3
  name: "Avery",
4
  role: "admin"
5
});
6
7
return { status: 201, body: { message: "User created" } };

pm.state.delete(key:String)

Removes the key and its value from the current mock session. This is useful when simulating deletes or cleanup. Resolves to true if the key existed.

1
await pm.state.delete("user");
2
3
return { status: 204 };

pm.state.has(key:String)

Checks whether a key exists in the current mock session. Resolves to true if the key is present.

1
if (!(await pm.state.has("cart"))) {
2
  await pm.state.set("cart", []);
3
}
4
5
return { status: 200, body: { ready: true } };

pm.state.keys()

Returns an array of all keys stored in the session state.

1
const keys = await pm.state.keys();
2
3
return {
4
  status: 200,
5
  body: {
6
    keys
7
  }
8
};

pm.state.size()

Returns the number of keys stored in the session state.

1
const count = await pm.state.size();
2
3
return {
4
  status: 200,
5
  body: {
6
    stateEntries: count
7
  }
8
};

pm.state.clear()

Removes all keys from the shared state used by the mock server. Use this to reset data between flows or simulate a full reset.

1
await pm.state.clear();

pm.state.toObject()

Returns the entire session state as a plain JavaScript object. This is useful for debugging or returning the current mock state in one response.

1
const snapshot = await pm.state.toObject();
2
3
return {
4
  status: 200,
5
  body: {
6
    state: snapshot
7
  }
8
};

pm.state.increment(key:String, delta?:Number)

Increments the numeric value stored at the given key by the specified delta (defaults to 1). If the key doesn’t exist, it’s created and initialized to the incremented value.

1
await pm.state.increment("retryCount");
2
3
const total = await pm.state.increment("totalRequests", 5);
4
5
return {
6
  status: 200,
7
  body: {
8
    retryCount: await pm.state.get("retryCount"),
9
    totalRequests: total
10
  }
11
};

pm.state.push(key:String, items:Array)

Appends one or more items to an array stored at the key. If the array does not exist yet, it is created automatically.

1
await pm.state.push("events", {
2
  type: "user.created",
3
  userId: "123"
4
});
5
6
return {
7
  status: 200,
8
  body: {
9
    events: await pm.state.get("events")
10
  }
11
};

pm.state.addToSet(key:String, item:Any)

Adds an item to an array only if it is not already present. Resolves to true if the item was added.

1
const added = await pm.state.addToSet("roles", "admin");
2
3
return {
4
  status: 200,
5
  body: {
6
    added,
7
    roles: await pm.state.get("roles")
8
  }
9
};