Skip to content

Data-Driven Runs

A run can be driven by a file: a row per iteration, its columns readable from the requests themselves and from scripts.

Two runs take one:

  • A collection run. Pick the file in the Run collection dialog, beside Iterations and Load test. Picking it declares it for the collection too, so the next run pre-fills it; the collection's Data tab declares one without starting a run.
  • A single request's load test (issue #993). Pick the file in the Run a load test dialog, under the profile fields. Picking it there declares it for the request's collection the same way, and a file declared anywhere is pre-filled here too (issue #1039). The request needs no collection wrapper: N users each sending the same request with different data is the canonical load shape, and until this it was expressible only by wrapping the request in a one-step collection.

What differs between them is only which row a given request binds - see How many iterations, and which row. The file, the refusals, the {{data.column}} namespace and pm.iterationData are the same on both.

This page is the file's contract - what Vayu accepts, what it refuses, and what a value becomes once it is bound.

Supported files

Extension Format Values arrive as
.csv Comma-separated, RFC 4180 strings, unless numbers are opted in
.tsv, .tab Tab-separated, same grammar strings, unless numbers are opted in
.json An array of row objects their JSON types
.jsonl, .ndjson JSON Lines - one object per line their JSON types

There is no XLSX support and no headerless mode. A spreadsheet exports to CSV in one step, and a file whose first row is data would leave every column unaddressable - see below.

The header row is the mapping

Column names become {{data.column}} tokens and pm.iterationData keys with no remapping step, exactly as Postman, JMeter and k6 work. A mapping UI would be a second source of truth for something the file already states.

That makes the header row's rules strict, and each refusal names the offending cell:

  • An empty header cell is refused - there is no name to address the column by.
  • A duplicated header cell is refused - {{data.user}} could mean either one.
  • A row with more or fewer values than the header names is refused, naming the row and both counts. A short row would leave a token unbound and a long one would drop cells nobody can see.

JSON and JSONL have no header, so the columns are the union of every row's keys, in first-seen order. A key that only some rows carry is a warning at pick time naming how many rows lack it - the iterations bound to those rows would fail on a {{data.*}} token naming it, but a column nothing references is harmless, so it does not block the run.

A header cell is free to name what a global, collection or environment variable already names - nothing here refuses that. While a row is bound, the column wins: {{username}} reads that row's username cell, above the active environment (issue #1007). With no row bound, the variable answers exactly as it would with no data file attached at all. Only the bare spelling collides this way; {{data.username}} addresses the column regardless, and never a variable. See Variable Resolution for the full ladder.

Values: strings from CSV, native types from JSON

A CSV or TSV cell is a string by default. 007 stays 007 and a 20-digit id survives, which is JMeter and k6 behaviour and the reason the preview says so. JSON and JSONL keep what the file declared - 3 is a number, true is a boolean, null is null.

Reading numbers as numbers is a per-file opt-in (castNumbers, issue

2540). With it on, an unquoted CSV or TSV cell that is a plain integer or

decimal arrives as a number: 3, -2, +4 and 3.5 as themselves, and 007 as 7 and 1.50 as 1.5, because dropping the padding is the point of asking. Everything else stays text:

  • a quoted cell, however numeric it looks - "007" stays 007, which is how one column of a file keeps its zeros while the rest become numbers;
  • 1e3, .5, 5., a hex value, NaN, Infinity, an empty cell, and a cell with spaces around it;
  • an integer outside the safe range (beyond 9007199254740991), so a 20-digit id still survives, and a decimal that would not print back as the digits the file holds (0.1000000000000000055511151231257827, or 0.0000001, which a number writes as 1e-7).

The header row is never cast. JSON and JSONL ignore the option, because the file already said what each value is. The preview notes which reading is in force.

Where to turn it on. The Read numbers as numbers checkbox sits in the picker's preview card, under the file's name, wherever the picker appears: the Run collection dialog, the load test dialog and the collection's Data tab. It is shown only for a CSV or TSV file. Toggling it re-parses the same file in place - the preview, the iteration count and the rows the run sends all follow, and the file stays picked. The setting belongs to the collection's file binding (stored on the collection beside the file's path), so the next Run dialog, load dialog, Send-with-row and Data tab read the file the same way. Picking a file starts it off, because it describes how that file is read; Remove (or clearing the contract) forgets it with the file. A load test of a request in no collection has no binding, so the setting lasts for that run only.

The run records it too. The setting rides the run beside the file's name and hash (dataFileCastNumbers on POST /runs), and the run's snapshot keeps it. The hash is of the file's bytes, so it cannot tell a file read as text from the same file read with numbers cast; the stored setting can. Wherever a past run names its file - the dashboard's config summary, History's Test config box and hover card, a collection run's header and context bar, a run tab's tooltip - the name is followed by "(numbers read as numbers)" when the run cast them, and comparing two runs of one file read both ways reports a data-file difference. A run recorded before the setting existed reads as text, which is how every such run was read. A collection run's header also says "(number reading changed since this run)" when the file's bytes are unchanged but its binding now reads numbers the other way. Running the collection again reads the file through its binding, so it casts the same way unless you change the checkbox.

This is the integer and decimal subset of what Newman's --csv-auto-parse reads. Newman is looser: it also casts 1e3, .5 and padded cells, so a file that leans on those arrives as text here and as a number there. How the Postman desktop app's collection runner types CSV cells is not verified.

A JSON or JSONL cell may also be an object or an array. It is bound as compact JSON, so {{data.address}} reads {"city":"Pune"}. A cell nested deeper than 100 levels is refused with its row and column named, for example Row 4, column "address" is nested more than 100 levels deep. The picker says so before the run starts, and the engine applies the same limit to a caller that sends rows without the picker (a script or an MCP client).

If you need a number to arrive as a number, use a JSON file or turn on number reading for the CSV - and write the token outside the quotes in the body, {"n": {{data.n}}}, because that is what decides whether it arrives as 2 or "2".

A null cell is a value pm.iterationData hands to a script and a value a {{data.column}} token refuses - see below.

Quoting (CSV and TSV)

The parser is RFC 4180, not a split(","):

  • A quoted field may contain the delimiter, newlines, and CRLF.
  • A literal quote inside a quoted field is written doubled: "say ""hi""".
  • A quote that does not open a field is an ordinary character, so 6" pipe needs no escaping.
  • Blank lines are skipped, and the count is reported as a warning.

A file that ends while a quoted value is still open is refused, naming the line the quote opened on. Reading it any other way would fold every remaining line into one cell, silently.

Encoding

Files must be UTF-8. A UTF-8 byte-order mark is stripped rather than becoming part of the first column's name.

UTF-16 with a byte-order mark is also read - that is what Excel's "Unicode Text" export writes. Anything else is refused: a Windows-1252 file (Excel's plain "CSV" on Windows) would otherwise arrive with question marks where the accented characters were, and it would parse cleanly, so nothing later could catch it. Re-save as UTF-8 and pick it again.

Size limits

Two engine settings bound a run's data set, and the app enforces both before the run rather than letting POST /runs refuse it afterwards:

Setting Default Bounds
maxScenarioDataRows 1000 How many rows one run may carry
maxScenarioDataBytes 16 MiB How large the data set may be

Both are editable in Settings -> Engine -> General, and the app reads the live values - raise a limit there and the same file is accepted without restarting anything. The row limit alone does not bound the payload, since one row is free to hold a megabyte in a single cell, which is why there are two.

The caps apply to a file re-read from its bound path exactly as they do to one picked by hand, and both refusals name the setting. That matters because neither side of the comparison holds still: a declared file grows rows after it was declared, and the setting itself can be lowered under a file that has not changed at all. So both run dialogs' pre-fill, Send-with-row and the Data tab each refuse a file over the cap instead of previewing it - the byte cap when the file is opened (the app's main process stats it before reading), the row cap once it is parsed, since counting rows means parsing and the engine never opens a file.

The engine never opens a file. The app parses it and sends the rows inline on the run payload, because the script sandbox has no filesystem access by design and handing the daemon a user-supplied path would be a new trust boundary. The row set itself is never stored on either side - a run's snapshot records its count plus the file's name, content hash and whether its numbers were read as numbers, never its path or a row - but a cell bound into a request travels with that request, and a run stores the requests it sent. See What is stored.

Reading a row: {{data.column}} vs pm.iterationData

Both read the same row. They differ in when:

  • {{data.column}} is substituted into the request - URL, headers, body, form fields - immediately before the send. Use it to make each iteration hit a different endpoint or send a different payload. See the {{data.column}} contract in the engine's HTTP API reference.
  • pm.iterationData is read by scripts, after the step's request was composed, so it cannot change where the request goes. Use it for assertions and for values a script derives. See Data rows.

{{data.id}} is a reserved namespace, not a variable tier: it and {{id}} are different names, so the prefixed spelling can neither shadow nor be shadowed by a global, collection or environment variable, and that never changes whether or not a data file is attached.

A bare column name is a different rule (issue #1007): while a row is bound, {{id}} itself resolves from that row's id column - at Postman's position, above the active environment - because Postman writes a dataset's columns bare and an imported collection is spelled that way. A column name may equal a variable name; while a row is bound the column wins, and with no row bound (a plain Send, or a run with no data file) the variable answers exactly as it always did. A bare name the bound row does not carry is not a failed bind - it is an ordinary variable, and falls through to the same scopes it would resolve from with no data file at all. See Variable Resolution for the full ladder and the D18 decision behind it.

A {{data.column}} naming a column the bound row does not carry fails the step before anything is sent. Substituting an empty string would send a request quietly pointing somewhere else, which is the failure this namespace exists to remove. A cell that is present but null fails the same way, for the same reason - the token says the value came from the file. A column that is legitimately empty for some rows belongs in a script, where pm.iterationData hands null to a branch that can read it.

A cell carrying quotes, backslashes or newlines is safe in a JSON body: a token inside a string literal is escaped as it binds, so say "hi" arrives as that text inside valid JSON rather than ending the string. A token written outside a string literal - {"n": {{data.n}}} - is not escaped, which is how a number arrives as a number: a JSON file's, or a CSV cell read as one. A cast 1.50 binds as 1.5 either way; inside quotes it is the text "1.5".

A cell is safe in an XML body too, and by a rule that reads the token's position rather than one that escapes everything:

Where the token sits What the cell arrives as
Element text &, < and > escaped - Ben & Jerry's arrives intact
An attribute value the above, plus whichever quote delimits that attribute
A <![CDATA[…]]> section byte for byte, which is what the section is for; a ]]> in the cell splits and reopens the section rather than ending it
A tag or attribute name - <{{data.tag}}> byte for byte: no escape is legal in a name
An XML comment or processing instruction nothing - the row is refused, naming the token

The comment and processing-instruction refusals are deliberate: neither is content the server reads, and a cell carrying --> or ?> would end the construct and change the document into one you did not write. Move the token into the element or attribute it belongs to.

Nothing else is escaped: a URL, a header, a form field and a plain-text body take the cell byte for byte - including a text body that happens to hold XML, because the mode you picked is what decides the rule.

A header is the one of those with a limit. A header line ends at a line break, so a cell holding ok followed by a newline and X-Admin: true would not put that text in the header - it would end the header and send the rest as a header of its own, which is a request your file never described. There is no escape for a line break in a header, so the row is refused, naming the token and the row. It applies to a header name, a header value, and a credential that goes into a header line - a bearer token, or an api key sent in a header. Basic auth's username and password are base64-encoded and an api key sent in the query is percent-encoded, so a line break in either is harmless and binds as written. A JSON or JSONL file is where this turns up: those keep the cell as the string it is, while the CSV grammar has no way to carry a raw newline into one.

The limit is the header's, not the data file's, so it holds for whatever put the bytes there: an environment variable substituted into a header is refused when the request is composed, naming the variable (variable resolution), and anything else - a script, an import, a request sent by another client - is refused just before it would go on the wire, naming the header.

A Send-with-row's preview shows all of this before you send (issue #2639). With a row picked, the Body tab's Resolved view and the key/value rows' resolved peek show a cell as the bind will write it - escaped inside a JSON string, escaped for its place in an XML body - and a row the send would refuse says so there: a warning above the Resolved view for a token in an XML comment or processing instruction, and a line under a header row's peek for a cell with a line break, naming "the picked row" where the send's own error says data row 0. A value the environment supplies is shown as composition writes it, unescaped (variable resolution).

How many iterations, and which row

One iteration per row by default: leave Iterations empty and the row count is the run's length.

Give an explicit Iterations count and it wins - row i % rows binds to iteration i, so a count above the row count wraps back to the top, and a count below it leaves the remaining rows unused. The picker states which of those is about to happen, because a 500-row file running once is the surprise this preview exists to remove.

A load run binds rows differently: every virtual user claims rows from one shared cursor, so no two start on the same row while unclaimed rows remain, and the rows then repeat for as long as the duration lasts. Once they wrap, users do share rows - size the file to the concurrency if that matters, or reach for what varies without a column. The row count says nothing about how long the run is.

A single request's load test is that same cursor with one request where a collection run has a sequence: one row is claimed per request sent, in turn, wrapping when the set runs out. So a 3-row file under a 6-request run sends rows 0, 1, 2, 0, 1, 2 - the file bounds which values the run sends and never how many requests it sends, which is the load profile's job. Iterations is not defaulted from the row count here, unlike a collection run: a load profile already says how long the run is.

What varies without a column

A file is one way to make iterations differ. A run has two more that need no column at all, and a data-driven load run usually wants all three at once. Variable Resolution owns their rules; what follows is what they mean beside a bound row.

{{$vu}} and {{$iteration}} name the run rather than the row (issue

994): which virtual user this request belongs to, 1-based, and which of that

user's iterations it is, 0-based. They are reserved names and not variables - a variable of either name does not answer for the identity - and they are substituted immediately before each send, so every iteration carries its own numbers. Neither needs a file: the identity comes from the iteration rather than from a row, so both bind on a load run carrying no data at all. What each shape of run answers is tabulated under $vu and $iteration are reserved too; the shape to know here is that a single request's load test is one user's iterations, so {{$vu}} is 1 there and {{$iteration}} is the counter that varies - the same counter the row cursor claims from, so iteration i holds row i % rows. A script renders them with pm.variables.replaceIn("{{$vu}}") (issue #1057), which reads the identity the request beside it was bound with.

The {{$guid}} family generates per iteration (issue #995). A run's request is composed once and then repeated, so the generators are left written as they stand and a fresh value is produced per occurrence, immediately before each send: two {{$guid}} in one body are two different ids, on every iteration. A plain Send still generates at composition, because it composes once and sends once. Which names generate, and why a run defers them, is the dynamic variables table.

All three at once. A collection load run of 20 users, driven by a tokens.csv of user,token, sending a request whose bearer token is {{data.token}}, whose X-Client header is vu-{{$vu}} and whose body carries "requestId": "{{$guid}}":

Token Where its value comes from What it varies with
{{data.token}} the row this iteration claimed per iteration, off the shared cursor
{{$vu}} the user sending it per virtual user, the same across that user's passes
{{$guid}} generated at the send per occurrence, per iteration

Write user-{{$vu}} into a basic-auth username instead of that header and it binds there too (issue #1055), even on a run with no data file at all: what defers a credential's build is the token the credential carries, not whether the run has rows to bind.

Credentials bind before the request's auth is applied, so a row or an identity token reaches the credential itself rather than the header the credential is built into - the order Send with a row describes. Basic auth is where the order shows, since it collapses username and password into one base64 value: a token still unbound by then would go out as base64 of its own text. That is also why a generator in a credential is resolved at composition rather than deferred like the rest - write {{$guid}} into the body or a header instead. OAuth 2.0 takes none of the three, for the reason that same section gives.

This is also the answer when the file is smaller than the concurrency. Rows repeat once the cursor wraps, while {{$vu}} and {{$iteration}} together name each iteration of the run exactly once, and a generator is fresh at every send.

Declaring the contract: the Data tab

Until a file is declared, nothing in Vayu knows a column exists at the moment you write {{data.email}} in a URL. Picking a file declares it, in any of the three places a file is picked: the collection's Data tab, the Run collection dialog and the Load test dialog (issue #2050). Its columns are declared the moment it loads, and the preview underneath is what was written. The Data tab is the place to do it without starting a run.

What that stores, and what it does not:

Where it lives Travels with the collection?
The columns On the collection, as dataSchema Yes - and through import
The file's path On the collection, as dataFile (with its name, the hash of its bytes and how its numbers are read) Into a workspace backup, yes; through an export or an import, never - and the app's own MCP server names it only to a client on this machine
The file's rows Nowhere No

The path is the location on the machine that picked the file. A backup restored on another machine brings it back as it was written: the Data tab shows it, struck through with the reason, until the file is picked again there. A stored path is not permission to read it - Vayu opens only a file you picked, dropped or opened with the app.

Declaring changes no binding rule - a token still binds from the row the run carries. What it buys is everything that needs to know the columns before a run:

  • Both run dialogs pre-fill. If the declared file is still where you left it, opening Run collection - or the Load test dialog for a request in that collection - re-reads it and previews it, ready to start. Move or rename the file and the dialog says so and offers the picker - it is a note, not a refusal. Which file that is follows the chain rule like everything else here: running a sub-collection that declares nothing offers the file its nearest declaring ancestor was given, because that is the contract the run binds against - and a request's load run resolves it from the request's own collection, up the same chain.

    The two dialogs differ in one thing only, and it is not about the file: a collection run with rows and no explicit count runs one pass per row, so picking a file there clears an untouched iterations of 1. A load run's length is its profile's - a duration, a request count, a search - so nothing about picking or pre-filling a file changes a single field of it. - The Data tab re-opens it too. Coming back to the tab reads the declared file again and lines it up against the contract with no re-pick: comparing them is what the tab is for, so it does not wait to be handed the same file a second time. Edit the file on disk and the drift shows on the next visit. A file that has moved has its name struck through beside the declared columns, and the picker stands. Picking a different file there does not compare it, it declares it: the comparison is what reopening the tab does, and that never writes. - A file that does not match is flagged, in both directions and in both places: a declared column the file is missing (every {{data.x}} written against it would fail to bind at iteration 1) and a column the file carries that the contract does not declare (usually the sign of a contract that has drifted, or of the wrong file). Both are warnings; the run is still yours to start. The two run dialogs also compare the file with the requests the run sends, and name any column a request references that the file does not carry ("The requests reference 1 column this file does not carry: email"), because every iteration that binds one fails before anything is sent. Run collection checks the collection's requests, and its whole subtree under Include nested collections; Load test checks the one request. - The engine's refusal names the columns. Starting a run whose requests carry {{data.*}} with no file is already refused before anything is sent; with a contract declared, that message lists the columns the collection expects, so it says which file to run with rather than only that one is missing.

  • The builder checks your tokens. With a contract in scope, a {{data.email}} that names a declared column reads as one, and a {{data.emial}} that names nothing declared is painted amber with the declared list in its tooltip - so a typo shows while you are typing it rather than at iteration 1. It is advice, not a refusal: an undeclared column still binds if the file you run with carries it.

  • The columns are offered while you type. {{data. completes them in the URL, params, headers and body, and pm.iterationData.get(" completes them in the script editors.
  • You can send one request against one row. A caret appears beside Send in the request builder whenever a contract and a declared file are both in scope; it lists the file's first rows, and picking one sends that request bound to that row - the tokens substituted, and pm.iterationData readable in both scripts. This is how you iterate on a script that reads a row without starting a whole run each time. See Send with a row.
  • The Data tab audits the collection. A Referenced columns panel splits the declared columns into the ones your requests use, the ones your requests name but the contract does not declare, and the ones nothing references - across this collection and every sub-collection that does not declare a contract of its own. What counts as a use is what a run actually binds: the URL, params, headers and body, and the credentials a step sends - a bearer token, a basic username and password, an api key's name and value - including the ones a request inherits from a collection. An OAuth 2.0 config is not among them: its token is fetched once when the run's plan is resolved, before any row exists, so a {{data.*}} there binds nothing. Scripts are scanned for literal pm.iterationData.get("column") arguments only - the request's own and the collection chain's, which run around every step - and the panel says so: a column name a script computes at run time cannot be seen from here.
  • An agent can read them too. Over MCP, list_collections (asked for fields: "full") and vayu://collections carry a declaring collection's dataSchema (columns, file name, when it was declared), so an agent building the data rows for run_collection or start_load_run knows which columns to supply. Where the collection is bound to a file, the row also carries dataFile: { path, fileName, hash }, so an agent on this machine can open the file itself, the way you would; hash is the SHA-256 of the file's bytes as they are on disk when the agent asks (the digest the app last read when the file cannot be read), the same digest a run records, so an agent can tell whether the file is still the one a past run used. castNumbers: true on it says the app reads the file with Read numbers as numbers on, so the agent can type its rows the same way and say so on the run with dataFileCastNumbers: true; absent, every cell is text. A run's file name is a name, never a path: one holding a / or \ is refused. A collection that declares nothing has neither - the ancestor walk above is left to the reader, the same as it is for variables. The rows never go over MCP: Vayu does not read the file for the agent. The path is named only by the MCP server inside the running app, which listens on loopback, so every client that sees it runs on the machine it is true of; the standalone stdio server has no record of paths and never names one. A single target's data rows on start_load_run also name their columns (the union across every row) to composition, so a bare {{email}} takes the row's value over a same-named environment variable, as it does in the app.

A sub-collection with no contract of its own uses the nearest ancestor's, the same way a variable defined on a parent collection is in scope below it.

In all three places the two gestures that name a file are the saves: picking a file declares its columns and binds the file, and Remove clears the contract and the binding, so removing a file and picking another leaves the second one's columns declared, not the first's. A file the picker refuses - over the row cap, a ragged CSV - changes nothing. A run dialog declares for the collection whose contract the run binds against: the nearest declaring ancestor, or the collection being run (the request's own, for a load test) when nothing above it declares. A request in no collection has no contract, so a file picked for its load test is only that run's input. The pre-fill is a read of the declared file, never a pick, so opening a dialog declares nothing. A declare that fails is a warning beside the picker and nothing more: the file stays selected, the run still sends its rows, and picking it again retries. On the Data tab, the buttons beside the picker cover what a gesture does not: Re-declare from this file appears when the re-opened file has changed shape on disk (or a save failed and the preview is still there to retry from), and Clear removes a contract whose bound file is gone, where the picker offers no Remove.

Vayu only ever re-opens a file whose extension is one of the formats above, and only up to the same maxScenarioDataBytes a run may carry - the bound path is not a general licence to read your disk. A re-opened file over maxScenarioDataRows is refused too, once it has been parsed, so a file that outgrew the cap says so here rather than at the next run.

Send with a row

Everything above is about a run. One thing is worth doing without one: a pre-request script that reads pm.iterationData, or a URL carrying {{data.id}}, used to be testable only by starting a collection run and digging the step out of the result - a run per line of script.

With a contract declared and its file still in place, the request builder grows a caret beside Send. It lists the first 20 rows of the file, and takes any row in it by number; pick one and the request is sent bound to it:

  • every {{data.column}} in the URL, headers and body is substituted from that row, exactly as a run's iteration would substitute it;
  • both scripts read the row as pm.iterationData, with pm.info.iteration 0 and pm.info.iterationCount 1 - the send is row 0 of 1;
  • the response lands in the response pane like any other Send, and the send appears in History like any other design run.

The caret is absent, not greyed out, when there is nothing to bind - no contract in the collection chain, or no file bound to the collection that declared it. A file that has moved says so when you open the list, and picking it again in the Data tab is the fix. So does a file over maxScenarioDataRows: a single send binds one row, but the file is the collection's data set, and one no run can use is not a set to pick a row out of.

Auth credentials bind on a single send too. A {{data.user}} in a basic-auth username, a bearer token or an api key takes the row's value the same way the URL and the body do, and it does so before the credentials are encoded

  • so the header carries the row's values rather than base64 of the token text. This is the same thing a collection run does per iteration, which is what makes a credentials file work identically under Send-with-row and under Run collection.

The exception is OAuth 2.0: its token is fetched from the token endpoint rather than written into the request, so no row can reach it, under either Send-with-row or a collection run. A {{data.*}} in an OAuth 2.0 config is refused by name rather than sent wrong - use a static credential there, or move the token into the request itself.

Any row, by number. The list is 20 rows because a popover is not the file, and the row a long run failed on - "iteration 501 · row 501" - is never among them. So the Row number field above the list takes any index the file has: typing one shows that row and selects it, and Enter sends with it. A number the file has no row for is refused by name ("the file has 500 rows") rather than clamped to the last one, because binding a row you did not ask for is worse than binding none.

From a failed step. A collection run's step card carries Repro row N, which opens the request that step ran with that row already selected and this list open on it (issue #730) - so reproducing a failure is the step's own action and one click on the row, rather than finding the request in the tree by name and then discovering its row is out of the list's reach.

The rows read for the picker are held for that send and nothing more. The send itself is stored like any other design send, bound values included - see What is stored.

What is stored

The row set is not. The rows ride the run payload and are dropped when the dialog closes - both dialogs, and both shapes of run. They are user data of unknown sensitivity - credentials, customer records - so neither the app nor the engine keeps the set, and the file itself is read fresh every time - whether you pick it or the dialog pre-fills it from the declared path. Declaring a contract does not change this: what is saved with the collection is the shape of the file - its column names, and its name for display - and where it is (its path, the hash of its bytes and how its numbers are read), never a cell of it. A run's stored snapshot records the row count plus the file's name and content hash (the SHA-256 of its bytes, so two runs can be told apart by the file that drove them) and, when it was on, Read numbers as numbers, never its path or a row. The count and the file's name are what a reader sees afterwards: the dashboard's header prints "N rows from users.csv" in its config summary, live from the launch config and then from the report, and History's Test config box lists it as Data: N rows · users.csv, under its Details disclosure. A collection run's tab says Data: users.csv in its header, the History row's hover card has a Data file line, and a run tab's tooltip ends with the name. Where the file the run's collection remembers now differs on disk from the one the run read, the collection run's header adds "(file changed since this run)": the app hashes the file when the tab opens and again whenever its window regains focus, so an edit made in another program shows up on return. The same bytes read the other way - Read numbers as numbers switched since the run - add "(number reading changed since this run)" instead, because the hash cannot tell the two apart; a changed file wins over a changed reading. A file that has moved or been deleted adds "(file no longer at that path)" instead, whether or not the run recorded a hash, and so does a file the app was never given by a pick, drop or open (a data file declared before that rule, #2357, reads again once it is picked once more); the desktop app is the only place that can tell, so the browser build never shows it. A file the app cannot hash for any other reason adds nothing; the hash itself is never shown. A file whose name holds a \ (legal on macOS and Linux) is run without its name, because a name with a path separator is refused as a path.

A cell that binds into a request is stored with that request. A collection run keeps one row per step execution, and each holds the exchange as it happened: the URL, the request headers as sent - including the Authorization header that binding-before-encoding builds out of the row's own values - the request body, and the response. A load run keeps the same material for the completions it samples, and a single Send with a row lands in History like any other send. So a run driven by a credentials file has each bound iteration's credentials in its history, in SQLite, and on screen in its step cards.

That is the design-mode trace rule, not an oversight of this feature: a trace records what was sent rather than a redacted account of it, since a redaction guess is wrong in both directions and reassuring when it is wrong. The run's step view carries that disclosure where the steps are listed, and names the data file when the run's snapshot recorded one.

The expiry is the run's: step rows are deleted when their run is, so maxRunsRetained (a collection run counts under it; design Sends have their own cap, maxDesignRunsRetained) and runRetentionDays (Settings, Data & retention) are what bound how long a bound cell lives. A run pinned as a baseline is outside both, and Settings' Clear run history keeps it too. Deleting the run by name deletes its rows immediately, pinned or not.