Captures: chain requests

A capture copies a value out of a response and stores it in a variable. The next request can then use it as {{name}}. This is how you log in once and reuse the token, or create an item and then fetch it by its new id, without copying and pasting.

Write a capture

Open a request and select the Captures tab. Write one capture per line:

name = source

name is the variable to fill. source says where the value comes from:

Source	Takes the value from	Example line
body. followed by a JSON path	A field of the JSON body	token = body.data.token
A JSON path on its own	The same; body. is optional	userId = data.user.id
header. followed by a header name	A response header	etag = header.ETag
status	The status code	code = status

JSON paths use dots for fields and [n] for list items, counting from 0: data.items[0].id. They work the same way as in Tests without code.

The tab's label shows how many captures the request has, for example Captures (2).

Rules

• Header names ignore case: header.etag and header.ETag are the same.
• A text value is stored as it is. A number or boolean is stored as its text (42, true). An object or list is stored as JSON text.
• A value that is missing from the response, or is null, is skipped. The variable keeps whatever it held before.
• A line without = is ignored.
• Captures run whenever a response arrives, whatever its status. They do not run when the request fails to get a response.
• A captured value overwrites a variable of the same name.

Where captured values go

Situation	The value is stored in
An environment is selected	That environment
No environment, and the request is saved in a collection	The collection's variables
No environment, and the request is not saved	Memory, until you close the app

Captures set the variable's current value, not its initial value. See Variables for the difference and for how scopes override each other.

TIP

Select an environment before you start. Captured tokens then stay in that environment, and you can switch to another environment without mixing them up.

Walkthrough: log in, then use the token

You need two requests in one collection: a login request, and any request that needs the token.

1. Open the login request. Suppose it answers with this body:

   { "data": { "token": "eyJhbGciOi...", "user": { "id": 7 } } }

2. Open its Captures tab and type:

   token = body.data.token
   userId = body.data.user.id

3. Open the second request. In its Auth tab choose Bearer Token and type {{token}} in the Token field. Use the user id in the URL:

   {{baseUrl}}/users/{{userId}}/orders

4. Send the login request. The variables token and userId now hold values.

5. Send the second request. It goes out with the fresh token and the right user id.

From now on, send the login request again whenever the token expires. Every request that uses {{token}} picks up the new value.

Not sure how tokens work? Read Auth basics.

Captures in the runner

The collection runner sends requests in order, so a capture in one request feeds the requests after it, in the same pass and in later passes.

The runner's Keep variable values switch decides what happens at the end:

• On (the default): captured values are saved to the environment or collection, as if you had sent the requests by hand.
• Off: the run works on copies. Captures still pass between its requests, but every change is thrown away when the run ends.

Captures in the load tester

The load tester starts each request's captures in its Extract (one per line) box. Open it with Extract values for later requests next to a request to view or edit them for that test.

Load tests treat captures differently:

• Each simulated user has its own set of values, so users do not overwrite each other's tokens.
• Values pass to later requests only in One by one mode. In All at once mode every request fires together, so there is no "later".
• A value is extracted only when the call passes.
• Nothing is saved to your environment or collection.

Captures on the command line

The command-line runner runs captures the same way as the collection runner. Values go to the environment you pass with -e, or to the collection's variables when you pass none. They last for that run only.

Captures or scripts?

Use a capture when you want one value from the body, a header or the status. Use a script when you need to change the value first, pick an item by a condition, or store it in a specific scope:

const items = pm.response.json().items;
const firstOpen = items.find((item) => item.status === "open");
pm.collectionVariables.set("openItemId", firstOpen.id);

If a value is not captured

The variable stays empty

Check the path against the real response. Open the response's Pretty tab and follow the path field by field. A common slip is a missing level, such as token when the body has data.token.

The next request sends the old value

Check which scope wins. A variable with the same name in a higher scope hides the captured one. See Variables.

Nothing is captured at all

The request may have failed before a response arrived. Look at the response panel or the Console for the error.

Next steps

• Collection runner: run a whole login-then-use chain in one go.
• Scripts: do more with a response than a capture can.
• Workflow testing: design tests that span several requests.