Skip to main content

Conditional Variables

Conditional variables extend reusable variables with filtering. They let you extract only items that match specific criteria, such as "only blocks where type = 'page'" or "only users where status != 'deleted'".

When to Use Conditional Variables​

Use conditional filtering when:

  • An API returns mixed data you need to separate
  • You want to process only certain types of items
  • The API doesn't support server-side filtering

Example Use Cases​

API ResponseFilterResult
All Notion blockstype = 'page'Only page blocks
All usersstatus != 'deleted'Active users only
All filesname ends with '.pdf'PDF files only
All recordsmetadata.archived existsRecords with archive flag

Creating Conditional Variables​

Step 1: Open the Conditional Variable Modal​

From the Variables Panel:

  1. Click + New Conditional Variable
  2. Or click Add Filter on an existing variable

Step 2: Select Source​

Choose the endpoint that provides the array data:

  • Only endpoints with test results are available
  • Test the source endpoint first if needed

Step 3: Choose Array Path​

Select which array to filter:

  • Common paths are suggested from the response
  • Shows item count for each array
  • Preview first item structure

Step 4: Define Filter Condition​

Set the filtering criteria:

Field: The property to check on each item

  • Supports dot notation for nested fields (user.profile.type)
  • Auto-complete shows available fields

Operator: How to compare

  • equals - Exact match
  • not_equals - Does not match
  • contains - Substring present
  • starts_with - Begins with value
  • ends_with - Ends with value
  • exists - Field is present and not null

Value: What to compare against

  • Auto-complete shows existing values in the data
  • Not needed for exists operator

Step 5: Preview and Confirm​

The modal shows:

  • Matching count: "15 of 42 items match"
  • Sample matches: First few matching items
  • Extract field: Which field to extract from matches

Step 6: Name and Save​

Give the variable a descriptive name that indicates both source and filter:

  • Good: PageBlocks, ActiveUsers, PdfFiles
  • Include filter hint: UsersNotDeleted, BlocksTypePage

Filter Operators​

equals​

Exact string match after type conversion:

Items: [{ type: "page" }, { type: "database" }, { type: "page" }]
Filter: type = 'page'
Matches: 2 items

not_equals​

Excludes matching items:

Items: [{ status: "active" }, { status: "deleted" }, { status: "active" }]
Filter: status != 'deleted'
Matches: 2 items

contains​

Substring search (case-sensitive):

Items: [{ name: "Report Q1" }, { name: "Summary" }, { name: "Report Q2" }]
Filter: name contains 'Report'
Matches: 2 items

starts_with / ends_with​

Prefix or suffix matching:

Items: [{ id: "user_123" }, { id: "org_456" }, { id: "user_789" }]
Filter: id starts with 'user_'
Matches: 2 items

exists​

Checks field is present and not null:

Items: [
  { id: 1, email: "a@x.com" },
  { id: 2, email: null },
  { id: 3 }
]
Filter: email exists
Matches: 1 item (only first has non-null email)

Nested Field Filtering​

Filter on nested object properties using dot notation:

Items: [
  { id: 1, meta: { type: "page", archived: false } },
  { id: 2, meta: { type: "database", archived: true } },
  { id: 3, meta: { type: "page", archived: false } }
]

Filter: meta.type = 'page'
Matches: items 1 and 3

Filter: meta.archived = 'true'
Matches: item 2

Applying Conditional Variables​

Conditional variables work exactly like regular variables:

  1. Apply to any parameter drop zone
  2. In iterate mode, target runs once per matching item
  3. Filter is applied at extraction time
Variable: PageBlockIds
  Source: List Blocks (returns 100 blocks)
  Filter: type = 'page' (matches 15 blocks)
  Extract: id

Applied to: GET /blocks/{blockId}/content
Result: Runs 15 times (only page blocks)

Editing Filters​

Modify Existing Filter​

  1. Find variable in Variables Panel
  2. Click Edit
  3. Adjust filter condition
  4. Preview updated matches
  5. Save changes

All endpoints using this variable will use the new filter on next test.

Remove Filter​

  1. Edit the variable
  2. Clear the filter fields
  3. Save as regular variable (no filtering)

Best Practices​

Filter at the Right Level​

For nested arrays like pages[*].blocks[*]:

  • Filter applies at the last array (blocks)
  • Can't filter pages and blocks independently
  • Create separate variables if needed

Check Filter Effectiveness​

Always preview match counts:

  • 0 matches = filter too restrictive or field name wrong
  • All items match = filter not filtering (check operator/value)
  • Expected subset = filter working correctly

Name Clearly​

Include filter intent in name:

  • ActiveUsers (implies filtered)
  • AllUsers (implies no filter)
  • UsersWithEmail (implies exists filter)

Document Complex Filters​

Use the description field for filters that aren't obvious:

  • "Filters to blocks created by the primary user"
  • "Excludes test accounts (email contains 'test')"

Troubleshooting​

"Filter matches nothing"​

  1. Check field name spelling (exact match required)
  2. Verify field exists on items (use exists operator to test)
  3. Check value format (strings are case-sensitive)
  4. Look at actual data in JSON viewer

"Filter matches everything"​

  1. Operator might be inverted (equals vs not_equals)
  2. Value might be empty or whitespace
  3. Field might have unexpected type

"Wrong items filtered"​

  1. Verify you're filtering the correct array level
  2. Check nested path is complete (meta.type not just type)
  3. Review sample matches in preview