Correlation and dynamic values

Problem: The server returns a value in one response — an order ID, a CSRF token, a session cookie, an ETag — that must be sent back in one or more later requests. Without correlation, VUs send stale or null values, causing cascading errors that inflate your error rate and make results meaningless.

Test type: Any stateful flow (Load test, API performance test).

Prerequisites

• A Taurus YAML scenario targeting your API.
• Knowledge of where the dynamic value appears: JSON response body, response header, HTML attribute, or cookie.

Types of extractors

Taurus supports four extraction strategies:

Extractor	Use when the value is in
extract-jsonpath	A JSON response body (most REST APIs)
extract-regexp	Anywhere in the response body (HTML, XML, arbitrary text)
extract-xpath	An XML or HTML response body
extract-css-jquery	An HTML element attribute (CSS selector)

The extracted value is stored in a named variable and available in all subsequent requests within the same VU iteration.

Step by step in MaxoPerf

1. Identify the correlation point

Before writing the YAML, send a request to the endpoint manually (curl or browser DevTools) and note:

• The response field that contains the dynamic value.
• The request field where the value must be sent back.

Example: a REST API returns {"order_id": "ord-abc123"} on POST /orders, and the client must pass order_id as a path segment on GET /orders/{order_id}.

2. Write the extraction

execution:
  - scenario: order-flow
    concurrency: 30
    ramp-up: 2m
    hold-for: 5m

scenarios:
  order-flow:
    variables:
      order_id: ''
      csrf_token: ''
    requests:
      # Step 1: Get a page that includes a CSRF token
      - label: GET /checkout
        url: https://app.example.com/checkout
        method: GET
        extract-regexp:
          csrf_token: 'name="csrf_token" value="([^"]+)"'

      # Step 2: Submit the form with the CSRF token
      - label: POST /checkout/submit
        url: https://app.example.com/checkout/submit
        method: POST
        headers:
          Content-Type: application/x-www-form-urlencoded
          X-CSRF-Token: ${csrf_token}
        body: 'cart_id=cart-001&csrf_token=${csrf_token}'

      # Step 3: Create an order and capture its ID
      - label: POST /orders
        url: https://api.example.com/orders
        method: POST
        headers:
          Content-Type: application/json
          Authorization: Bearer ${AUTH_TOKEN}
        body: '{"items": [{"sku": "ABC", "qty": 1}]}'
        extract-jsonpath:
          order_id: '$.order_id'

      # Step 4: Use the captured ID
      - label: GET /orders/{order_id}
        url: https://api.example.com/orders/${order_id}
        method: GET
        headers:
          Authorization: Bearer ${AUTH_TOKEN}

3. Handle missing extractions

If the extraction fails (the pattern does not match), Taurus sets the variable to the string <extraction-failed>. You can detect this with an assertion:

      - label: POST /orders
        # ...
        extract-jsonpath:
          order_id: '$.order_id'
        assert:
          - contains: '${order_id}'
            not: '<extraction-failed>'

Default value for safety

Append |default_value to your JSONPath expression to supply a fallback: $.order_id | ord-fallback. This prevents downstream requests from sending a null path segment and generating false 404 errors.

4. Upload and run

1. Open the test in MaxoPerf, switch to Files, and upload the YAML as the entrypoint.
2. Bind any secrets (AUTH_TOKEN) under Settings → Secrets.
3. Click Run now.

5. Inspect the per-label breakdown

1. Open the run and look at the per-label throughput and error-rate table.
2. If GET /orders/{order_id} has a high 404 rate, the POST /orders extraction is failing — check the JSONPath expression.
3. If POST /checkout/submit returns 403, the CSRF regex is wrong — inspect the HTML source for the actual token field name.

Verify

• All labels after the extraction step show 2xx responses at the expected rate.
• No label shows <extraction-failed> in error samples (check the Log tab).
• The VU-count and throughput in the overview match the concurrency setting.

Variations

• Header extraction: Taurus’ extract-regexp works on headers too when you use the subject: headers option.
• Multiple extractions on one response: list multiple extract-jsonpath keys on the same request.
• JSONPath arrays: use extract-jsonpath with match-no: -1 to extract a random element from an array response.
• JMeter: use Regular Expression Extractor or JSON Extractor post-processors — see JMeter JMX on Maxoperf.
• k6: assign response.json('$.order_id') to a variable and pass it in the next request — see k6 scripts on Maxoperf.

Where to go next

• Auth login + token capture flow — the common login → token → action pattern.
• REST API CRUD load test — a full CRUD recipe that uses extract-jsonpath for the created resource ID.
• Taurus fundamentals — complete extractor reference.