Skip to main content

Reusable Variables

Reusable variables let you save a data extraction once and apply it to multiple endpoint parameters. Instead of creating individual mappings for each use, you define a variable that captures where data comes from.

Input Variables​

Input variables inject fixed or per-collection values into endpoint URLs and query parameters. They appear at the top of the Variables panel and are defined on the connector, not extracted from responses.

Types​

TypeDescription
StaticA fixed value stored on the connector (e.g. a shared tenant slug, API version)
RuntimeNo stored value — prompted when each collection starts

Creating an Input Variable​

  1. Open the Variables panel
  2. Click + Add input variable
  3. Choose Static or Runtime
  4. Set the variable name (used in {{variable_name}} templates)
  5. For Static: enter the fixed value
  6. For Runtime: optionally enter a test value — used only during connector building so real requests work. The test value is never published.
  7. Optionally set a display label (shown in collection start form for runtime variables)
  8. Optionally set auto-apply to parameter — automatically wires the variable to every endpoint that has a matching path or query parameter name

Using Input Variables​

Reference the variable anywhere in a URL path or query parameter using {{variable_name}} syntax:

https://{{base_domain}}/api/v2/users
/orgs/{{org_id}}/repos

Variables are also supported in the Token Endpoint URL field, enabling connectors where the token endpoint varies per customer.

What Are Extracted Variables?​

Extracted variables represent:

  • A source endpoint (where data comes from)
  • A JSON path (what data to extract)
  • A default mode (iterate or first)
  • Optionally, a filter condition (see Conditional Variables)

Once created, you can apply the variable to any parameter on any endpoint.

Variable Types​

Traces supports three types of variables:

TypeDescriptionUse Case
StandardExtracts values from a single endpoint responseMost common — e.g., user IDs from a list endpoint
PairedCombines outer/inner value sources into correlated pairsCorrelating related data — e.g., user IDs with their org memberships
MergedCombines values from multiple variables into oneAggregating IDs from multiple list endpoints

See Paired Variables and Merged Variables for detailed guides.

Creating Variables​

From the JSON Viewer​

  1. Test an endpoint to see its response
  2. Click on a value in the JSON viewer
  3. Click Save as Variable in the selection popover
  4. Enter a name (e.g., "User IDs", "Channel Names")
  5. Choose default mode:
    • Iterate: Target endpoint runs once per value
    • First: Use only the first value

From the Variables Panel​

  1. Open the Variables Panel (bottom of the right panel)
  2. Click + New Variable
  3. Select source endpoint
  4. Choose JSON path from response
  5. Name and configure the variable

Using Variables​

Applying to Parameters​

  1. Select an endpoint in the tree
  2. Find the parameter drop zone (path, query, or body)
  3. Click the Variable icon on the drop zone
  4. Select from available variables
  5. The mapping is created automatically

Applying via Drag and Drop​

  1. Open the Variables Panel
  2. Drag a variable chip
  3. Drop onto any parameter drop zone

Variables Panel​

The Variables Panel shows all saved variables:

ColumnDescription
NameVariable identifier
SourceEndpoint providing data
PathJSON path being extracted
Modeiterate or first
Used ByCount of endpoints using this variable

Expanded Details​

Click a variable to expand it and see:

  • Which endpoints currently use this variable
  • Extracted values preview
  • Filter condition (if configured)
  • For paired variables: outer/inner sources and pairing mode
  • For merged variables: constituent variables

Panel Actions​

  • Edit (pencil): Modify variable settings
  • Delete (trash): Remove variable (disconnects all mappings)

Variable vs Direct Mapping​

AspectVariableDirect Mapping
ReuseApply to many endpointsSingle use
EditingUpdate once, affects allEdit each individually
FiltersSupports conditionsNo filtering
OrganizationNamed and visibleImplicit

Use variables when:

  • Same data feeds multiple endpoints
  • You need to filter array data
  • You want clear documentation of data flow

Use direct mappings when:

  • One-off parameter filling
  • Quick testing
  • Simple connector with few dependencies

Variable Modes​

Iterate Mode​

When applied to a parameter, the target endpoint runs once for each extracted value:

Variable: userIds (from users[*].id)
Values: ["u1", "u2", "u3"]

Target: GET /users/{userId}/posts
Runs 3 times:
  /users/u1/posts
  /users/u2/posts
  /users/u3/posts

First Mode​

Only the first value is used:

Variable: primaryOrg (from organizations[0].id)
Values: ["org1"]

Target: GET /orgs/{orgId}/settings
Runs 1 time:
  /orgs/org1/settings

Best Practices​

Naming Conventions​

Use descriptive names that indicate:

  • What data the variable contains
  • Whether it's filtered (for conditional variables)

Good: ActiveChannelIds, PageTypeBlocks, UserEmails Bad: var1, data, ids

Variable Organization​

  • Group related variables by source endpoint
  • Delete unused variables to reduce clutter
  • Use paired or merged variables for complex data flows instead of many individual variables

Mode Selection​

  • Default to iterate for array data that should all be processed
  • Use first for lookups where any value works
  • Consider API rate limits when iterating over large arrays

Troubleshooting​

"Variable shows 0 values"​

  • Test the source endpoint first
  • Verify JSON path matches response structure
  • Check if filter condition is too restrictive

"Changes to variable don't apply"​

  • Variables are applied at test time
  • Re-run dependent endpoint tests after modifying
  • Check that the variable is actually used (not a direct mapping)

"Can't delete variable"​

  • Variables in use show a warning
  • Remove mappings using the variable first, or confirm deletion