Vayu Engine API Reference¶
Base URL: http://127.0.0.1:9876 (default, configurable via --port)
All endpoints return JSON. Every response also carries Cache-Control: no-store
(#1507) - see Listeners for why. Every error
response has one shape - an error
object carrying a machine-readable code and a human-readable message:
code is per-status unless the route names a more specific one: bad_request
(400), unauthorized (401), forbidden (403), not_found (404), conflict
(409), bad_gateway (502), unavailable (503), insufficient_storage (507),
internal_error (any other 5xx). Routes
with their own vocabulary pass it instead - invalid_config (POST /config),
invalid_run_config (POST /runs), precondition_failed and
invalid_if_match (the If-Match of a whole-record PUT or of
POST /globals), and the oauth2_* family.
Any per-error detail sits inside the same object, so a client reads one
place for the whole failure - item on POST /import/apply, the provider's
reply on /oauth2/*:
{
"error": {
"code": "oauth2_provider_error",
"message": "Token endpoint refused the request (HTTP 401): invalid_client",
"providerStatus": 401,
"providerError": "invalid_client"
}
}
Most routes used to emit a flat {"error": "message"} instead, which the app's
http-client could not read - every validation message surfaced as a bare
HTTP 400 (issue #173). The client still accepts the flat shape so a newer app
can read an older engine, but the engine no longer produces it.
Who may call the API¶
The engine serves no browser. No response carries a CORS header, and the
request gate in server.cpp refuses, before any route runs, for every route:
- a request whose
Hostis not exactly127.0.0.1:<port>,localhost:<port>or[::1]:<port>(the port this engine bound) -403, message naming the Host check. This is what defeats DNS rebinding, where a page reaches the listener under a name it controls and is same-origin with it; - any request carrying an
Originheader, whatever its value (nullincluded) -403, message saying the engine does not serve browser origins.
A request cpp-httplib refuses to parse never reaches that gate: an HTTP/1.1
request with no Host, any request with more than one, or a Host holding a
byte outside uri-host [ ":" port ] (RFC 9112 §3.2) is answered 400 with an
empty body and the connection closed. An HTTP/1.0 request with no Host still
reaches the gate, and is refused there with the 403 above.
An OPTIONS request that passes the Host check is answered 204 with no body
and no CORS header, whatever its Origin: a preflight that grants nothing
leaks nothing. Local tools (the CLI, curl, the MCP server's fetch) send no
Origin and are unaffected. The Electron shell is the one browser-context
client: it strips Origin from the renderer's requests and supplies the CORS
response headers the renderer needs itself (app/electron/engine-origin.ts).
What a browser page can still send is a request with no Origin: a scriptless
GET (<img>, <script>, <link>, a no-cors fetch, a top-level
navigation) to the loopback name it dialled. That passes the gate and reaches
a GET route. It is harmless because two things hold together: the response
is opaque to the page (no CORS header, and the browser's CORB/ORB keeps a JSON
body out of a <script>), and no GET route has a side effect. A page
can therefore neither read the engine nor change it, though it can make the
engine run any GET handler.
Writes to file trust need one more thing: the grant secret. Host and
Origin decide who reaches the API at all; they cannot tell the Vayu app from
any other local caller (a script, the CLI, the MCP server, another process).
What a request body may send from disk is decided by the allowed folders and
the picked files, so the four routes that change those -
POST/DELETE /file-roots and
POST/DELETE /file-grants - also require the
header X-Vayu-Grant-Secret to carry the engine's per-start secret, and answer
403 with code grant_secret_required otherwise:
- The app's main process generates the secret and passes it in the engine's
environment as
VAYU_GRANT_SECRET. The engine reads it once at start, before any thread exists, and removes it from its own environment, so nothing it later reads or starts sees it. On Linux and macOS it also overwrites the bytes the kernel passed (what/proc/<pid>/environshows on Linux), whichunsetenvalone leaves readable; on Windows the environment block is private to the process. A value shorter than 32 characters is ignored with a warning that does not print it. - The header is compared in constant time (both sides hashed with SHA-256, the
digests compared with
sodium_memcmp). A missing header, an empty one and a wrong one are the same403. The secret is never logged (the request log records method, path, status, time and size, never a header) and no response carries it, a refusal included. - An engine started without a secret refuses all four writes, whatever the
header says. That is every engine the app did not start:
vayu-enginerun by hand, or one the CLI or a CI job starts. Folders allowed and files picked before then still apply to every send, andGET /file-rootsandGET /file-grantsanswer as usual.
The engine's own outbound client sends exactly what this gate admits, a
loopback Host and no Origin, so the engine never sends a request to its own
port or the MCP server's - not from a script, a redirect or a name that
resolves to loopback. See Reserved local ports.
Request bodies¶
Every request body is judged from its headers, on the same pre-routing handler as the gate above, before any route runs and before a byte of the body is read (issue #1824):
- A body sent with
Transfer-Encoding: chunkedanswers411Refused: the engine reads a request body only when its length is declared up front - send Content-Length, not Transfer-Encoding: chunked, on every route. A chunked body's size is known only once it has been read, and cpp-httplib's read bound is fixed for the listener's life, so it could not follow a body-size setting changed while the engine runs. The app,vayu-cliand the MCP server all sendContent-Length. - A
Content-Lengthover 151 MiB (158334976 bytes) answers413Request body is N bytes, over the limit of M the engine reads for any request, on every route. The ceiling is fixed and derived from the largest values the two body-size settings accept:maxSpecDocumentBytesat its 100 MiB maximum under the import rule below, which also coversmaxScenarioDataBytesat its own 100 MiB maximum. Raising either setting never meets this ceiling first. POST /import,/import/parseand/import/documentcarry a whole document and are held to a tighter bound that follows the livemaxSpecDocumentBytes, checked first because its message names the setting; see the body cap under POST /import/parse.
Both refusals are the shared error shape, with code error. Because the body
is not read, the engine answers and closes the connection: a client that is
still writing a large body may see the connection reset rather than the
response.
Once read, every route that reads a JSON body holds it to a depth bound: one
nested deeper than 128 levels answers 400 request body is nested deeper
than 128 levels before the route reads a field, and text that does not parse
answers 400 Invalid JSON: <parser message> (issues
#2417,
#2671). Both carry code
bad_request unless the route has one of its own for a malformed body, which
the depth refusal then shares: invalid_compose_request on POST /compose,
oauth2_invalid_config on the /oauth2/* routes, mock_issuer_invalid_config
on /mock-issuer, invalid_config on POST /config. POST /execute and
POST /runs hold the same bound; see their sections. A route that accepts an
empty body (POST /mock/start, POST /mock-issuer/start, the /inbox writes)
reads it as no body at all rather than as a parse failure. The import routes
are held to the same 128 levels: their documents travel as a string
(content) or as flat lists linked by temp ids, so a legitimate body is far
shallower. A document's own nesting is
bounded separately, where the engine reads it.
The bound reads the body's own tree, so JSON carried inside a string field is
not covered by it. The engine parses three such fields again and holds each to
the same 128 levels itself (issue
#2672): a request's
postmanProtocolBehavior string (POST /requests), and a
graphql or jsonrpc body's content (the graphql
envelope, the jsonrpc
envelope).
Removed route aliases¶
The execution and run/metrics routes were consolidated behind a /runs family,
/execute, and /runs/:id/metrics (#83). The pre-consolidation paths served as
deprecated aliases for a release cycle and are now gone; each answers 404.
| Removed | Use |
|---|---|
POST /request |
POST /execute |
POST /run |
POST /runs |
GET /run/:id |
GET /runs/:id |
DELETE /run/:id |
DELETE /runs/:id |
POST /run/:id/stop |
POST /runs/:id/stop |
GET /run/:id/report |
GET /runs/:id/report |
GET /metrics/live/:id |
GET /runs/:id/live |
GET /stats/:id?format=json |
GET /runs/:id/metrics |
GET /stats/:id (SSE) |
GET /runs/:id/live while the run is retained, then GET /runs/:id/report |
GET /runs with no query parameters no longer returns the pre-pagination bare
array: it answers the {data, pagination} envelope at the default page size, the
same as any other call (see GET /runs).
Resource writes: create vs update¶
Collections, requests and environments follow one write contract. /globals is
a singleton and stays POST-only, so it is exempt from the verb split below -
but not from the null-vs-absent rule, which it follows with every write treated
as a create (see POST /globals).
| Verb | Path | Meaning | Wrong-target status |
|---|---|---|---|
POST |
/<resource> |
Create only. | 400 when the body carries an id |
PUT |
/<resource>/:id |
Update only (merge-patch). | 404 when the id does not exist |
PUT is used loosely as a merge-patch rather than a whole-record replace: an
omitted field keeps its stored value. We deliberately did not add a separate
PATCH verb - merge-patch is what the update path has always done, and every
client call site expects it. The :id in the path is the record's identity; the
body carries the changed fields only.
An update is atomic against a concurrent one. The read the merge is computed
from, the merge itself and the write are one acquisition of the database lock, so
two clients patching one record at the same moment - the app's autosave and an
MCP agent, say - each merge onto what the other committed rather than onto the
row as both of them found it. The alternative is not a conflict but a silent
loss: the merge carries every field the body did not name, so the loser's fields
come back written with the values the winner read a moment earlier, and neither
request fails. A client that computes its body from an earlier read (a
read-merge-write across two round trips) closes its own window with
If-Match.
Conditional updates with If-Match¶
The four whole-record PUTs - collections,
requests, environments and
examples - take an optional If-Match
header (issue #2433), and so does
the globals singleton's whole-blob save, POST /globals
(#2988). A row's version is its
updatedAt, and its entity tag is the weak W/"<updatedAt>".
- Every
200from those writes, and fromGET /requests/:idandGET /globals, carries the row'sETag. The list reads (GET /collections,GET /environments,GET /requests/:id/examples) carry no per-row header; a client builds the tag from the row'supdatedAt, which is the same value. If-Match: W/"<updatedAt>"makes the write conditional: it lands only while the stored row is at that version. The check runs inside the same lock acquisition as the read and the merge, after the404, so the row it judges is the row the write replaces.- A mismatch is
412with codeprecondition_failed, and nothing is written. The storedupdatedAtrides inside the error, so the caller can re-read, merge again and retry under the new tag:
{"error": {"code": "precondition_failed", "message": "The record changed after it was read; read it again and re-apply the change", "updatedAt": 1792359304908}}
If-Match: *holds for any stored row (a missing one is still404). A comma-separated list holds when any member names the version, and repeatedIf-Matchlines are read as one list. The comparison is weak:W/is ignored on both sides, where RFC 9110 asks for the strong comparison, which no weak tag passes. Every tag the engine issues is weak because a row's answer carries members itsupdatedAtdoes not version (a request's derived file trust).- A value that is not
*or entity tags (a bare1792359304908, an empty value) is400invalid_if_match, before the row is looked up. - No
If-Matchis the unconditional write it always was. The app sends none: its autosave patches only the fields that changed (#1436), so its writes merge rather than collide.
An update through these routes always moves updatedAt forward, even within one
millisecond, so two of them never share a tag. Other writers of these rows (a
reorder, a spec sync, a run persisting script variables, an import's globals)
stamp the current time. Activating an environment clears isActive on the one it
replaces without restamping that row, so an environment's tag does not cover
isActive.
Globals has no 404: an engine that never saved any answers the empty set at
updatedAt: 0, and W/"0" is that version's tag. A first conditional save
names it, and once anything is written it is stale like any other.
The engine owns every id¶
A create must not carry an id. The engine generates one via generate_id,
giving the <prefix>_<uuidv4> form, and a body containing the field is a 400:
{"error": {"code": "bad_request", "message": "id is assigned by the engine; omit it (bulk import: POST /import/apply)"}}
Presence alone is rejected, null included - id is not a settable field with a
default, so the null-vs-absent rule below does not
reach it, and accepting {"id": null} would leave a caller believing the field
is honoured. The field existed for the import orchestrator, which pre-assigned
ids so it could wire parentId / collectionId across a whole tree before
anything was persisted; import sends one
POST /import/apply instead, referencing items by opaque
tempId and reading the real ids back from idMap (issues #96, #97).
On PUT, the path is the identity. A body id matching it is accepted and
ignored; one that disagrees - including null - is a 400
(message Body 'id' must match the id in the path ('col_1') or be omitted),
because the payload otherwise names two different records and guessing between
them is how a PUT to one id rewrites another. This is checked before the record
is looked up, so a malformed body answers 400 whether or not the target exists.
Since no create can select an id, the pre-existing "id already exists" 409 -
whose body names the update path, e.g.
message Collection 'col_1' already exists; use PUT /collections/:id to update -
is now reachable only on a generate_id collision, which 122 bits of entropy put
out of reach. It stays as a guard: on that draw the alternative is overwriting a
live record.
The null-vs-absent rule¶
One rule, identical for every field of all three resources:
| Field absent | Field explicitly null |
|
|---|---|---|
Create (POST) |
use the default | use the default |
Update (PUT) |
keep the current value | reset to the default |
The defaults are {} for variables, the resource's own default for auth
({"mode":"none"} for a collection, {"mode":"inherit"} for a request), []
for params / headers, "" for description and the two script fields,
{"mode":"none"} for a request body, true for followRedirects, 10 for
maxRedirects, null for a request's timeout (the defaultTimeout setting,
read at each send), and false for isActive.
order is the one default that is computed rather than constant: it means
"append after the current siblings", on both resources and on both verbs - see
Ordering below.
A request's httpVersion is the one field whose default is not fixed: absent
or null seeds it from the live defaultHttpVersion config entry ("auto"
unless changed), read fresh on every write rather than cached - see
POST /requests. Unlike every other field above, an
unrecognized httpVersion value is rejected with a 400 rather than silently
coerced, because a typo'd protocol silently running as HTTP/1.1 is the worst
available outcome.
A field that has no default cannot be reset, so null is a 400 on either
verb rather than a silently discarded write. Those fields are a collection's
name, an environment's name, and a request's collectionId, name,
method and url. Each is also required on create.
A storage failure is not a 400¶
A create or update whose request was fine but whose database write failed does
not answer 400 (issue #2423), because a 4xx tells the caller to change the
request and the app does not retry one. It is told apart by SQLite's own result
code, and the body never quotes SQLite's text (the engine log does):
| Cause | Status | code |
The caller should |
|---|---|---|---|
The disk holding the data is full (SQLITE_FULL) |
507 |
insufficient_storage |
free space, then repeat the call |
The database stayed locked past the busy timeout (SQLITE_BUSY, SQLITE_LOCKED) |
503 with Retry-After: 1 |
unavailable |
repeat the call |
| Any other SQLite failure (I/O error, read-only file, corruption) | 500 |
internal_error |
read the engine log |
An exception that is not SQLite's (a body that is not JSON, a field that fails
validation) stays a 400. Every handler of a resource write answers through
send_exception in routes.hpp; SendExceptionGuard fails the build on one
that goes back to a bare 400.
A stored JSON field has a write-time cap¶
One rule, identical for every resource (issue #1485): a request's params /
headers / body / auth, a collection's variables / auth / dataSchema
/ openapi / specFile / dataFile, and an environment's variables are each
refused with a 413
when the serialized value is over the engine's field cap (10 MiB,
json::MAX_FIELD_SIZE in engine/include/vayu/core/constants.hpp) - naming
the field, its size and the cap, and leaving the stored row untouched. POST
/import/apply enforces it too, through the same apply_*_field helpers every
other write goes through.
A row written before this cap existed can still be oversized. GET
/<resource>/:id always answers with the field whole, however large it is -
this did not change. Only a request's list route, GET
/requests?collectionId=, behaves differently: it has always substituted the
field's documented default for a column too large to serve efficiently across
a whole page, and now names which fields it substituted for that row in a
truncatedFields array (e.g. ["body"]), omitted when nothing was. Neither
GET /collections nor GET /environments substitutes or carries this field -
see GET /requests.
Ordering¶
Collections and requests both carry an order column that fixes their position
among their siblings. The siblings of a row are every child of its parent, of
both kinds (#2535): a collection's sub-collections and its requests share one
order space, so a request can sit between two folders.
Reading. GET /collections and GET /requests each sort by order
ascending, then createdAt ascending, then id ascending. All three keys are
load-bearing: order alone is not a total order (every request created before
explicit orders existed sits at 0), and rows are stored with INSERT OR
REPLACE on a TEXT primary key, which hands the row a new rowid on every edit -
so without an explicit tiebreak, renaming a request silently moved it among its
ties.
A client that lists a parent's children merges the two lists by order, and on
an order tie ranks the sub-collection before the request, ahead of
createdAt and id: the sibling order is (order, kind, createdAt, id), which
within one kind is the three-key rule above unchanged. The engine's copy is
engine/include/vayu/db/sibling_order.hpp; the app's compareTreeOrder is
pinned to it by engine/tests/fixtures/tree-order-conformance.json, read by
both test suites. A recursive
collection run walks the same merged list
depth-first, a request where it sits and a sub-collection's whole subtree where
the sub-collection sits, pinned across both consumers by
engine/tests/fixtures/recursive-run-order-conformance.json; a mock server's
route table and POST /specs/export list a subtree in that order too.
A workspace from before schema version 7 numbered the two kinds apart, each
from 0, and showed every sub-collection above every request. The version-7
migration moves each collection's requests past its highest sub-collection
order, so that display survives (docs/engine/db-schema.md, Schema versions);
rows still tied at the legacy 0 keep it through the tie rule.
Writing. order defaults to "append after the current siblings" - one past
the highest order any sibling of either kind holds:
| Write | order |
|---|---|
Create, order absent or null |
appended |
Create, order stated |
as given, if an integer from 0 to 2147483647; otherwise a 400 |
Update, order stated |
as given, if an integer from 0 to 2147483647; otherwise a 400 |
Update, order absent, no move |
unchanged |
Update, order absent or null, and the row changes parent (a collection's parentId, a request's collectionId) |
appended in the destination |
Update, order null, no move |
appended among its current siblings |
A move that states no order therefore lands at the end of the destination rather
than at whatever slot its position in the old list happened to name, after its
folders and its requests alike. Ordering within a list is always the caller's
to state, and a stated order may put a request between two sub-collections.
A stored order is an integer from 0 to 2147483647 (#3451), so a
negative, truncated or wrapped slot cannot be written. A stated order outside
that range or that is not a JSON integer ("3", 2.5, -1, 2147483648) is
a 400 naming the field on every route that writes one
(POST/PUT /collections, POST/PUT /requests,
POST /reorder, POST /import/apply, POST /specs/sync),
for example Invalid 'order': must be an integer from 0 to 2147483647 (got 2.5),
and nothing is written. An append under a parent where a sibling already holds
2147483647 has no slot left, so it is a 400 naming order too
(Cannot append: a sibling already holds 'order' 2147483647 ...) rather than a
row that wraps to the top; state an order, or renumber the parent with
POST /reorder's normalize, which frees the end again. An import document's
own stated order (x-vayu-request.order, an x-vayu-collection.folders
entry's order) outside the range counts as unstated, so the row takes the
position an unordered one would.
Bulk import is the one exception to the append scan: POST /import/apply
writes rows that cannot see each other yet, so an omitted order gives the
payload's items consecutive slots per parent starting from the append point, one
run across both kinds - the parent's sub-collections first, in payload order,
then its requests - see POST /import/apply. POST
/specs/sync numbers the folders and requests it creates the same way.
Any writer producing several sibling rows at once owes them distinct
orders - the import applier is the instance of a general rule, not a special
case. The createdAt leg is a millisecond stamp, so rows written inside one
tick tie on it and fall through to id, which compares random UUIDs: stable
across reads of the same data, but arbitrary with respect to the order the
caller meant. Single-row creates need nothing extra, because the append scan
already sees every stored sibling and hands out a fresh slot. The rule is on the
writer rather than on a finer timestamp: a microsecond stamp would still tie
under a fast enough writer, and it would make row identity depend on clock
resolution across the three platforms Vayu builds on.
Repositioning several rows at once is POST /reorder, not a
run of PUTs. Each PUT is one row under its own lock, so a reorder expressed
as N sibling PUTs can be interrupted halfway, leaving two rows at one order
and a gap where the moved one was, and a concurrent client's move lands between
any two of them. The batch endpoint validates and writes the whole set under one
lock scope, which closes both. What is not a difference any more is the cycle
guard: since a PUT holds its own read to its own write, its guard and its write
are one scope too, so two conflicting reparents sent as single PUTs are
serialized and the second is refused against the first's committed graph - it is
refused after that first move is already stored, which is the part only a batch
avoids. The per-row PUTs remain correct for a single row - a rename, a move
that appends - and still carry those caveats when used in a loop.
Paged lists¶
GET /collections, GET /requests,
GET /trash and GET /cookies answer every row
they hold by default. Three optional query parameters ask for one page of them
instead, and a page cuts the route's own documented order (the three-key rule
above for collections and requests, newest first for the trash, scope then jar
line for cookies), so consecutive pages neither skip nor repeat a row while
nothing is written between them (#2443):
q- case-insensitive substring of the row'sname(for a cookie, itsnameor itsdomain). The fold is ASCII only:A-Zmatcha-z, and any other letter matches only as typed, soÉdoes not findé. Empty matches every row. Rows the route never lists (a request or collection in the trash, a cookie cleared from its jar) never match.limit- page size, an integer from1to500; default50.0, a value over500or anything that is not a whole unsigned integer (5abc,-1,+5, empty) is a400with codeinvalid_limit, never a clamp.offset- matching rows to skip, a non-negative integer; default0. Anything else is a400with codeinvalid_offset. An offset past the end is an empty page, not an error.
Naming any of the three (?q= alone counts) switches the answer to the
envelope GET /runs uses:
{
"data": [ ... ],
"pagination": { "total": 812, "limit": 50, "offset": 0, "returned": 50, "hasMore": true }
}
data holds the rows the route's own answer would have carried, cut to the
page; total counts the rows matching q before the page was cut, read from
the same fetch as the page; hasMore is offset + returned < total. Naming
none of them answers exactly what the route answered before paging existed,
byte for byte: a bare array for GET /collections and GET /requests,
{items, total} for GET /trash, {scopes} for GET /cookies. Filtering and
slicing run in memory over the route's ordinary fetch, so a page saves the
transfer and the client's parse, not the engine's read.
Accepted field shapes¶
A field that is present and not null must have the shape below, on both verbs.
Anything else is a 400 naming the field, e.g.
message Invalid 'auth': must be a JSON object.
| Field | Shape |
|---|---|
variables (collection / environment / globals) |
object |
auth (collection / request) |
object |
body (request) |
object - see The request body union |
params / headers (request) |
array of {key: string, value: string, enabled: bool} |
order (collection / request) |
integer from 0 to 2147483647 - see Ordering |
parentId (collection) |
string: a collection id, or null or "" for the root |
every other plain string field (name, description, url, bodyType, an example's body and contentType, a certificate's host and passphrase, ...) |
string; the 400 is Invalid '<field>': must be a string (got <type>) |
Object-shaped fields are stored as JSON blobs, and every reader of one degrades
quietly when it is not an object - variables reads back empty, a request body
is dropped, and auth resolves to none, so a request the caller believes carries
credentials goes out bare. The write is therefore rejected rather than stored:
{"variables": 42} and {"auth": "bearer"} are 400s, and the previously
stored value is left untouched.
parentId: "" is the root, the same as null (#3451). It is stored as
null on POST/PUT /collections (a folder POST /specs/sync creates
with "" or null lands under the synced collection), and
POST /reorder reads it as null in a move and in a
normalize scope, so the tree has one spelling of the root: a collection
created with "" is appended among the roots and lists with them. A value
that is neither a string nor null (5, true, an object, an array) is a
400 such as
Invalid 'parentId': must be a collection id or null (got number). Rows an
older engine stored with "" are rewritten to null at startup
(the empty-parent pass), so a
delete and restore of one comes back where it was instead of re-parented to the
root.
A variables key must be one a {{ name }} token can reach (#3251). A token
is looked up with the spaces, tabs, CR and LF around its text cut, so a stored
key that is empty, whitespace-only, or differs from its trim can never be
referenced. The same 400 refuses it, naming the key: Invalid 'variables': key
' x ' has leading or trailing whitespace, or ... key '' is empty or
whitespace-only. It applies to POST/PUT /collections,
POST/PUT /environments and POST /globals, and the stored value is left
untouched. Whitespace inside a key and dots are fine (my var, a.b).
Variables a script writes are not checked. An import does not hit this: it
trims the names it reads, see POST /import/parse.
Blank names¶
A collection's or environment's name that is empty or only spaces, tabs, CR
and LF is a 400 on POST/PUT /collections and POST/PUT /environments
(#3253): Invalid 'name': is empty or whitespace-only. The row is not written.
A PUT that does not state name keeps the stored one, so a row that is
already blank stays editable. A name with content is stored as written,
surrounding spaces included. POST /import/apply and POST /specs/sync are
not held to this: they carry names an importer wrote, and a blank one imports
as it always did. The MCP create_ and update_ tools for both resources
refuse the same name as an input error before calling the engine.
Collection auth¶
A collection's auth is never {"mode":"inherit"} (#3445). A collection, a
folder included, is a link of the chain a request inherits through, so its own
inherit would mean nothing the walk could use: the composer steps past it,
while a client reading the row would show the parent's credential as the
collection's. POST/PUT /collections answer 400 (Invalid 'auth': a
collection cannot inherit auth ...) when the body states an auth object whose
mode is inherit, and write nothing. A body without auth is not judged (a
PUT keeps the stored value), and "auth": null resets to {"mode":"none"},
which is how a collection stops being an auth source. POST /import/apply and
POST /specs/sync are not held to this, as with blank names. A
row that already stores inherit from before this rule is read as no auth of
its own: POST /compose resolves a request beneath it to the nearest ancestor's
credential, and a PUT of other fields still succeeds. The MCP create_ and
update_ collection tools refuse inherit as an input error before calling the
engine.
Auth modes¶
A stored auth object's mode is one of none, noauth, inherit,
bearer, basic, apikey, oauth2, digest, aws, ntlm, hawk,
oauth1, edgegrid and jwt, spelled exactly so (#3464). The last seven are
stored and never executed: a send names the mode in authNotice and goes out
without a credential. Modes match by exact lowercase string, so Bearer,
" inherit" or a non-string mode would be stored and then read as a concrete
credential that stops the inherit walk and is sent as none.
POST/PUT /collections and POST/PUT /requests therefore answer 400
(Invalid 'auth.mode': must be a string, one of: ...) when the body states an
auth object whose mode is missing, not a string, or outside that set, and
write nothing. inherit stays valid for a request and is refused for a
collection (#3445). "auth": null and an absent auth are
not judged, and an auth that is not an object is the
shape 400. POST /import/apply and
POST /specs/sync are not held to this, as with blank names: an
importer's unrecognised mode is stored as written, so one odd block cannot fail
an atomic import. The MCP create_ and update_ tools for both resources refuse
an unknown mode as an input error before calling the engine.
The request body union¶
body is a discriminated union on mode, and the shape of what it carries
depends on which mode it is. The same union is read on the execution endpoints
(POST /compose, POST /execute, POST /runs) and stored on a request row,
so a body that round-trips through storage sends the same bytes.
mode |
Carries | On the wire |
|---|---|---|
none |
nothing | no body; a POST sends Content-Length: 0 and no Content-Type |
json / text |
content (string) |
content, verbatim |
graphql |
content (string) |
the GraphQL-over-HTTP envelope on POST, query parameters on GET (see below) |
jsonrpc |
content (string) |
the JSON-RPC 2.0 call envelope (see below) |
xml |
content (string) |
content, verbatim |
x-www-form-urlencoded |
fields |
percent-encoded key=value&… |
form-data |
fields |
multipart/form-data, boundary engine-generated |
binary |
file (a file reference) |
the file's bytes, verbatim (see File references) |
fields is an array of {key: string, value: string, enabled?: bool} - the
same row shape params and headers use. key is required and must be a
string; value defaults to "" and a non-boolean enabled reads as enabled.
A form-data row may add contentType, the part's own Content-Type, on a text
part as well as a file part (a Postman import writes it for a text row that
carries one); a part without it sends none.
A form mode carrying no fields array is a 400, as is a fields on a mode
whose content is a string. Rows with enabled: false are stored and returned
but never sent, so switching one back on needs no re-compose; {{variables}}
resolve inside key, value, contentType on a part, and a file reference's
src / fileName / contentType (a file part's, or a binary body's file)
during composition.
The Content-Type rules follow from the encoding:
x-www-form-urlencodedsetsContent-Type: application/x-www-form-urlencodedonly when the request declares no Content-Type of its own - an explicit header wins.jsonsetsContent-Type: application/jsonunder the same rule (issue #889). It did not until then, and libcurl's default for aCURLOPT_POSTFIELDSbody (every mode butform-dataand a streamedbinary, on every verb) isapplication/x-www-form-urlencoded- so a request whosebody.modesaidjsonwent out declaring itself a form. The app's body panel wrote the header row for a request built in the UI, which is why it survived: every request created any other way - MCPcreate_request, an import, a payload posted straight to/execute- sent the wrong type. A declared header still wins, soapplication/vnd.api+jsonreaches the server unchanged.graphqlandjsonrpcsetContent-Type: application/jsonunder the same rule - a Content-Type the caller wrote wins.graphqlonly on the method that carries a body at all: a GraphQLGEThas no body and derives no Content-Type, since there is nothing to describe (see below).textsetsContent-Type: text/plainunder the same rule (issue #2464). Until then it derived nothing, by decision -text/csv, a JWT and a raw signature are alltext- but an author who wrote no header got libcurl's form type rather than no type. Postman and Bruno sendtext/plainfor the same body. A typed row (text/csv,application/jwt) still wins, anddisabledSystemHeaders: ["content-type"]sends none.xmlsetsContent-Type: application/xml, again only when the caller declared none. It has no envelope and nothing is done tocontent; the header is the whole of what sets the mode apart fromtext, which is why an endpoint expectingapplication/soap+xmlkeeps the header it was given.-
form-dataalways sets its own Content-Type, and a caller-supplied one is dropped. The header has to carry the boundary of the body that was actually encoded, which no caller can name in advance. -
binaryderives its Content-Type from the file, in four tiers, an empty string counting as absent at each: an enabledContent-Typeheader row, thenfile.contentType, then the type the file's extension names (one engine table of common types), thenapplication/octet-stream.POST /composewrites the effective type into an emptyfile.contentType(unless a non-blankContent-Typeheader row is present, which wins at send anyway), so the composed payload - and a snippet generated from it - names the type the send uses.
No request goes out under libcurl's x-www-form-urlencoded default
(issue #2464). libcurl writes that type into any CURLOPT_POSTFIELDS body,
and into a bodyless POST, whenever the header list names no Content-Type. So
where nothing declares one - a content-type refusal in
disabledSystemHeaders, a typed Content-Type row left blank (on any mode but
binary, where a blank row is absent), a body mode of none on a POST - the
engine hands libcurl its removal line instead, and the request carries no
Content-Type at all, as Postman sends a bodyless POST. A bodyless PUT,
PATCH or GET never had one. The removal line is not a sent header and is
not in requestHeaders.
The graphql envelope¶
A GraphQL server reads its query out of a JSON object, so a graphql body is
enveloped on its way to the wire rather than sent as typed. content may be
either shape and the engine normalizes both:
content |
Sent as |
|---|---|
a JSON object with a string query |
itself, byte for byte |
| anything else (a bare document, JSON that is not an envelope) | {"query": <content>} |
The pass-through is byte-exact deliberately: the envelope also carries
operationName, variables and whatever else a server has agreed with its
clients, and re-serializing it would reorder keys the caller never edited. The
app's request builder writes the envelope itself, so its requests take the
first row; MCP and raw callers can hand over the document alone and take the
second.
One case is neither: content that looks like a JSON object ({ then a
quoted key) but does not parse - an envelope whose {{token}} went unresolved,
or a mistyped one - is passed through unchanged rather than wrapped. Wrapping a
body the engine could not read would turn a broken envelope into a valid
request carrying the wrong query. A bare GraphQL document cannot take that
shape, so nothing legitimate falls into it.
GraphQL-over-HTTP defines two transports, and the request's method picks between them (issue #1228). Everything above is the POST transport - the envelope goes out as a JSON body. On a GET, the same fields travel as percent-encoded query parameters instead, and the request has no body and no derived Content-Type:
| Parameter | From |
|---|---|
query |
the envelope's query, or the whole of content when it is a bare document |
operationName |
the envelope's operationName, when present and not null |
variables |
the envelope's variables, JSON-encoded, when present and not null |
extensions |
the envelope's extensions, JSON-encoded, when present and not null |
The order the author wrote is the order sent: the parameters follow the
envelope's member order, and the keys inside variables and extensions keep
theirs (issue #2789), written compactly with no whitespace. The encoding
re-renders numbers from their parsed value rather than copying the text: an
integer up to 64 bits unsigned (18446744073709551615) is exact, a larger one
becomes a double (18446744073709551616 is sent as 1.8446744073709552e+19),
and a fraction or exponent form is a double (1e2 is sent as 100.0). The POST
transport is unaffected and stays byte for byte.
These parameters are merged into whatever query string the request's URL
already has, not used to replace it - a GET sent to /graphql?debug=1 keeps
debug=1 alongside query=…. The engine sends a body on a GraphQL GET in
three cases, each because dropping the alternative would send a request the
caller did not write rather than the one it wrote: content is empty, content
is envelope-shaped but does not parse (the same unreadable-envelope case
above), or the envelope carries a member this transport has no parameter for,
or one of operationName / variables / extensions whose value is not the
type the specification gives it. A fourth case is an envelope nested deeper than
128 levels, its own root counted (issue #2672): content is a string, so the
request-body depth bound never looks inside it, and encoding variables or
extensions would re-serialize them recursively. Like the unreadable envelope
it is not split, and the engine does not guess at it. In all four, the request
falls back to the POST-style JSON body even though the method is GET.
The jsonrpc envelope¶
A JSON-RPC 2.0 server refuses a frame that does not declare its version, so a
jsonrpc body is completed on its way to the wire in the same place, and by the
same rule, as the graphql one. content may be either shape:
content |
Sent as |
|---|---|
a JSON object with a string jsonrpc member |
itself, byte for byte |
| a JSON object without one | itself plus "jsonrpc":"2.0", and "id":1 if it declares no id |
| a JSON array (a batch call) | itself, verbatim |
| anything else (a non-object, text that does not parse, or a call nested deeper than 128 levels) | itself, verbatim |
The added id is the constant 1, never a random or time-derived value: a
load run sends the same call thousands of times and a replay has to send the
bytes it replays, so a per-send id would make two runs of the same request
incomparable. A caller who needs their own ids writes the full frame - which is
passed through - and so does a caller sending a notification, the frame with
no id that a server must not answer. Members the caller wrote keep the order
they wrote them in, and the two the engine may add go on the end.
The member's type is what is checked, not its presence: {"jsonrpc": 2.0} is
the JSON number and the spec asks for the string, so such a frame is completed
(the version stamped over) rather than sent as the invalid request it is.
A batch array needs nothing done to it - every element carries its own envelope - and passes through for the same reason any non-object does: there is no single call object to complete.
The unresolved-{{token}} caveat is the graphql one, and it matters more here
because a JSON-RPC params is where a variable usually sits. Composition
resolves the body first (POST /compose), and the envelope rule then runs on
the resolved text; a body still holding a token at wire time does not parse,
so it is passed through as typed rather than completed into a well-formed
request carrying an unresolved template.
File references: binary bodies and file parts¶
Two body shapes name a file on the machine running the engine. They carry a path, never bytes, and answer to one rule.
A binary body is one whole file:
{
"mode": "binary",
"file": {
"src": "/home/ada/fixtures/avatar.png",
"fileName": "avatar.png",
"contentType": "image/png"
}
}
A form-data file part is a row with "type": "file":
{
"mode": "form-data",
"fields": [
{ "key": "caption", "value": "my avatar", "enabled": true },
{
"key": "avatar",
"type": "file",
"src": "/home/ada/portrait.png",
"fileName": "profile.png",
"contentType": "image/png",
"enabled": true
}
]
}
| Member | Meaning |
|---|---|
type |
Form rows only: "text" (default) or "file". Any other value is a 400. |
src |
Absolute path of the file. Required. |
fileName |
The name the file goes by. Defaults to the basename of src. |
contentType |
A binary body's Content-Type tier (above); a file part's own Content-Type, else derived from its name (see Sending, below). A text part takes it too (see above). |
unresolved |
Read-only, derived by the engine on every read (below): true when src is a concrete path this machine would refuse. Accepted and ignored on input. |
Shape refusals (400):
mode: "binary"without afileobject, or afileobject on any other mode. An engine older than this shape sent a binary body bodiless, which is why the workspace schema moved to version 3 with it.- A file part in an
x-www-form-urlencodedbody - that media type's wire form is a string of pairs and has no file form. - A
srcon a part that is not"type": "file": it names a file nothing would send.
The trust rule. Vayu sends a file under a folder you allowed in Settings
(Allowed folders), or a file a person picked
(Picked files, #2356). A reference is sendable when its canonical path lies
under an allowed folder or equals a picked file's: containment is decided on
canonical paths, component by component, so a symlink inside an allowed folder
that points outside it is outside, and /data/fixtures-old is not under
/data/fixtures; a picked file is the canonical path recorded when it was
picked, matched exactly, so a link re-pointed after the pick names another file
and is refused. What a request body says about trust is ignored: the
unresolved member an older client sends is accepted and dropped, on
POST /execute, POST /runs, POST /compose and every write, so no caller can
claim a file was chosen. A path composition or a data row fills in is held to
the same rule as a literal one. Scripts can never choose a path: the
residual pass after the pre-request script resolves a reference's fileName
and contentType but never src.
unresolved is derived on read. No stored body carries the key: the
request writes (POST/PUT /requests, POST /import/apply, POST /specs/sync)
and a run's configSnapshot drop it, and the
schema version 6 migration
removed it from every body stored before. Every read that hands a body to an
editor writes it back as the engine's answer for this machine now:
GET /requests, GET /requests/:id, the POST/PUT /requests responses,
POST /reorder's request rows, GET /runs/:id's configSnapshot.body and
POST /import/parse. true means a concrete path that is neither under an
allowed folder nor picked, which the send would refuse; false means an
allowed path or one still holding {{ (decided after composition). A
reference with no path carries no unresolved at all.
Every enabled reference is checked, in this order, and the first failure refuses the send:
srcis empty:"Body file has no file selected - ..."(a part:"Form field 'avatar' has no file selected - ...").srcstill holds{{: an unresolved variable.- The file does not exist or cannot be read:
"...: cannot read file '<path>' (<reason>)". - Untrusted:
"Body file '<path>' was not picked on this machine and is not under an allowed folder - pick it again in the request, or allow its folder in Settings › Files". - Not a regular file (a directory, a FIFO,
/dev/zero): refused. - It cannot be opened: refused, naming the path and the reason.
On POST /execute a refusal is the pre-send gate's shape: 200 with
statusCode: 0, errorCode: INTERNAL_ERROR and the message above in
errorMessage. A streaming execute (stream: true) answers 400 with code
unsendable_file. POST /runs checks every file the run can send before the
run row exists and answers 400 with code unsendable_file; for a path a data
row binds, each distinct bound path is checked and the message starts with
data row N: (a scenario's with Step N ('name'): too). A path that changes
per iteration in a way no row explains (an identity or generator token) cannot
be checked ahead and is refused per submission.
Sending. The check runs once per send and once per run, never per
transfer. It opens the file it approved, on the path the check resolved and
without following a final symlink, and everything after reads that open file,
never the path again: a link re-pointed or a file replaced at the path after
the check, or between a run's iterations, is not what is sent. A binary
body of at most 4 MiB is read through it in that pass and its bytes are
shared by every transfer of the run; a larger one is hashed through it in that
pass and every transfer streams from it (Content-Length from the size the
open saw; a redirect rewinds it). A form part's file is read from it by
every transfer of the send or run. A path a data row binds is the exception:
it is checked when the run starts but opened per submission, through the same
check again, so a large data file holds no file open per row. A streamed body's
or a part's length is the one the open saw; a file truncated below it under the
open handle fails the transfer.
A part with no declared Content-Type is typed by its filename's extension, then
its path's, from libcurl's table (gif, jpg, jpeg, png, svg, txt,
htm, html, pdf, xml), else application/octet-stream. A disabled
file part is neither checked nor sent.
What a record keeps. A view of a request never carries a file's bytes: the
raw-request view shows <file avatar.png, 1234 bytes> in their place. A binary
body's send records bodyFile: {fileName, size, sha256} (sha256 lowercase
hex; size and sha256 absent when the send was refused before the file was
read) - never the path:
| Where | JSON path |
|---|---|
POST /execute response |
bodyFile (top level) |
A design send's or a collection run step's stored trace (GET /runs/:id, result.trace; GET /runs/:id/results) |
trace.request.bodyFile |
| A single-request load run | config_snapshot.bodyFile, echoed by GET /runs/:id/report as metadata.bodyFile |
| A scenario run's steps | config_snapshot.scenario.steps[i].bodyFile (absent for a step whose path a data row binds) |
The older mode spellings form (for x-www-form-urlencoded) and formdata
(for form-data) are still accepted on input; responses always use the long
names.
Behavior change (pre-1.0)¶
A create carrying an id is now a 400 on all three resources. External
scripts that minted their own ids must drop the field and read the engine's id
out of the response, or use POST /import/apply for a whole
tree. A PUT whose body id disagrees with the path id is a 400 for the same
reason (it used to be silently ignored, so the write landed on the path id).
POST /<resource> used to be a silent upsert on all three resources, so a
client could send an update as a POST. That no longer works; external scripts
that relied on POST-as-update must switch to PUT /<resource>/:id. Two bugs went
with the old behavior and are fixed here:
- A stale or typo'd
idsilently created a second record instead of failing, and anidcollision silently merged two records into one. POST /environmentshad no null guard, so{"variables": null}stored the literal four-character textnull- JSON that parses but is not an object, so every reader saw an environment with no variables and no error. It now resets to{}like every other resource.environments.isActivewas honored only on create; it now follows the rule on both verbs.
Health & Configuration¶
GET /health¶
Check engine status and version.
Response:
workers is the workers setting's effective value: the configured count
when it is set, otherwise the detected core count - the same value the next
run's EventLoop will use, not the machine's raw core count regardless of
configuration. It is never 0: a host whose core count cannot be detected
reports 4, the fallback the event loop applies too.
dataDir (issue #3328) is the data directory this engine keeps its database,
logs and lock file in, the --data-dir it was started with, so a client can
tell an engine serving its own data from one serving another's. It is resolved
once at startup and always present:
- absolute: a relative
--data-dir(or the default./data) is resolved against the directory the engine was started in; - lexically normalised:
.and..segments and a trailing separator are removed, and on Windows every separator is\; - not canonical: a symlink is reported as written, not resolved, so the value compares equal to the path a client passed;
- UTF-8. A name that is not valid UTF-8 (a POSIX directory name is bytes) has the offending bytes replaced with U+FFFD rather than failing the response.
recovery (optional, issue #922) - present only when this engine startup had
to recover the database, and absent on a clean start rather than null:
{
"status": "ok",
"version": "0.3.0",
"workers": 8,
"dataDir": "/home/someone/.config/Vayu",
"recovery": {
"outcome": "started_fresh_quarantined",
"at": 1755870000000,
"databasePath": "/home/someone/.config/Vayu/db/vayu.db",
"quarantinedPath": "/home/someone/.config/Vayu/db/vayu.db.corrupt-1755870000000"
}
}
| Field | Meaning |
|---|---|
outcome |
restored_from_backup - <db>.bak passed the same validation and was restored over the corrupt database. started_fresh_quarantined - no backup restored it, so it was moved aside and a fresh one created. backup_also_corrupt - a backup existed, failed the same validation, and was left untouched rather than restored. deleted_corrupt - it was deleted, which an engine older than issue #984 always did and this one does only when the quarantine rename fails |
at |
When that happened, epoch milliseconds |
databasePath |
The database file it happened to |
quarantinedPath |
Where the unopenable database was moved to, readable with sqlite3 <path> .recover. Optional - absent for deleted_corrupt and for markers written before #984, so test for it rather than deriving it from outcome |
The node is read from a marker file beside the database and stands until a later
recovery overwrites it, so a client that has already told the user about an
event should key off at rather than expecting the node to disappear. See
db-schema.md.
POST /shutdown¶
Gracefully shut down the engine. This is the shutdown path the Electron app uses
on quit (it is more reliable than a signal on Windows, where SIGTERM does not
behave as expected).
The response is sent before shutdown begins, so the client always receives
the 200. The handler sets the body and then calls the shutdown callback
inline, which only wakes the daemon's main loop; the teardown cannot overtake
the response, because stopping the server joins the worker that is writing it.
The daemon then stops the server (and with it every mock server, inbox, mock
issuer and OAuth callback listener, a paced answer going out at once and a
callback's token exchange cancelled), ends and joins every streaming design run
(the run ends stopped and its trace's endReason is shutdown, never a
user's stopped, #3342), stops and joins active runs (a run still
sending ends stopped; one in its natural-end drain has the drain cut short, its
in-flight transfers counted as cancelled, and keeps its own end, as for
a Stop, issue #3341), refreshes the
recovery backup <db>.bak if the session wrote anything (bounded at 2 s and by
what is left of the app's 5 s window; on a timeout the previous backup stands,
see db-schema.md), closes the
database, releases the lock file, flushes the logs and exits.
Response: 200
GET /config¶
Get global configuration settings. Backed by the config_entries table. The
response is an entries array; each entry carries its value plus the UI metadata
the Settings panel renders (label, description, category, default, and optional
min/max/options):
{
"entries": [
{
"key": "workers",
"value": "8",
"type": "integer",
"label": "Worker threads",
"description": "Number of background worker threads. Higher values improve throughput on multi-core systems but increase RAM usage. Default equals CPU core count.",
"category": "general_engine",
"default": "8",
"min": "1",
"max": "128",
"requiresRestart": false,
"advanced": false,
"keywords": ["cores", "parallelism"],
"updatedAt": 1234567890
},
{
"key": "defaultHttpVersion",
"value": "auto",
"type": "enum",
"label": "Default HTTP version",
"description": "Protocol a newly created request starts with...",
"category": "network_performance",
"default": "auto",
"options": [
{ "value": "auto", "label": "Auto" },
{ "value": "http1.1", "label": "HTTP/1.x" },
{ "value": "http2", "label": "HTTP/2" }
],
"requiresRestart": false,
"advanced": false,
"keywords": ["h2", "alpn"],
"updatedAt": 1234567890
},
{
"key": "dbCacheSize",
"value": "67108864",
"type": "integer",
"label": "Database cache size",
"description": "Memory SQLite keeps per connection for recently used database pages...",
"category": "general_engine",
"default": "67108864",
"min": "1048576",
"max": "1073741824",
"unit": "bytes",
"requiresRestart": true,
"advanced": false,
"keywords": ["ram"],
"updatedAt": 1234567890
}
]
}
Only entries this engine's own build declares are listed (issue #1492): a
row a newer engine wrote to the same workspace, then left behind for an
older one to reopen, is never in entries - this engine has no label,
validator or bounds for it, so serving it would describe a setting it cannot
actually explain. POST /config applies the same rule to writes: a key
outside this build's catalogue is refused as "Unknown config key", the same
message a key with no stored row at all gets.
min and max are present only for entries that declare them (numeric
types). options is present only for type: "enum" entries - a JSON array of
{value, label}, so the renderer can draw a picker without a second,
hand-maintained value-to-label map. value and default are always strings;
type is one of integer, number, boolean, string, or enum.
dependsOn (issue #1610) is present only on an entry that means nothing
until a boolean sibling in the same category is on - correlationIdHeader
carries "dependsOn": "correlationIdEnabled". It is a catalogue fact the seed
asserts is internally consistent (a value naming an unknown, cross-category or
non-boolean key fails engine startup); POST /config never reads it back. The
Settings screen nests the dependent's card immediately beneath its parent's,
indented and disabled with a "Turn on \<parent label> to use this" hint while
the parent reads "false".
requiresRestart and advanced are booleans, always present:
requiresRestart- the running engine keeps the old value until it is restarted; anything else takes effect on the next run, inbox or request that reads it. It is the only statement of that fact: labels and descriptions no longer spell it out, and the app renders one chip from this field (a pending signal in the Dock too, once such a setting has been saved). Consumers must read the field rather than parse the label - the old(Requires Restart)suffix drifted out of step with the mechanism and misinformed the settings screen and the MCPupdate_configresult at the same time. Exactly three entries carry it -dbCacheSize,dbBusyTimeoutanddbSynchronous, all read when the database is opened.workerscarried it too until #873, which is the same drift in the field's own terms: the engine reads it at the start of every run, so the restart it asked for was never needed.config_route_test.cpppins the set.advanced- an internal with no everyday user story (dbBusyTimeout, the fouroauth2Refresh*watchdog knobs,inboxLivePollIntervalMs,sseIdleTimeoutMs,maxStepsPerIteration,monitorScrapeTimeoutMs,liveMaxRetainedTicks,scriptStackSize- eleven entries). Still live and still settable; the app renders these collapsed under an "Advanced" section at the bottom of their category. The membership rule is citable: if an entry's own description has to say "only if" or "only for", the entry has declared itself advanced.
keywords is an array of strings, always present and empty for the entries
that declare none - a client never has to tell "declares none" from "this
engine does not send the field". They are extra terms the app's settings search
matches on: what a user types that this entry's key, label and description
never say ("ram" for dbCacheSize, "deadline" for defaultTimeout, "fsync"
for dbSynchronous). They are match terms only and are never displayed, and a
seeded keyword never repeats a word the entry already carries - search reaches
the other three fields first and ranks them higher, so a duplicate would only
push the entry above better matches. A test over the seeded catalogue enforces
both halves of that.
unit says what a numeric entry's value measures - ms, sec, days or
bytes today - and is omitted when the entry measures nothing, the same
shape as min / max / options above rather than a null. Absent means the
number is a count (worker threads, retained runs, stored steps); a suffix
reading "items" would be noise, so counts declare none. Non-numeric entries
never declare one.
The app renders it as the suffix inside the input, which is where a unit is
stated once - so a seeded description never spells the same unit out as an
"in milliseconds" clause, and a label never carries a (ms) suffix; a test
over the catalogue enforces both. Labels are sentence case ("Default request
timeout", "Correlation ID"), enforced by a second catalogue test. bytes
additionally selects human-readable formatting for the value, the range hint and the default line (104857600
reads as 100.0 MB), which the app used to select from a hardcoded list of
three keys - so a byte-valued entry added engine-side was formatted as a raw
number until someone edited a TypeScript array. A client that meets a unit it
does not know should show it verbatim rather than drop it.
Three entries are seeded as enum today. defaultHttpVersion is the protocol a
newly created request starts with (see POST /requests).
It is a write-time seed only - changing it never alters a request that already
exists, and it is never consulted at execution time. dbSynchronous is
SQLite's durability level, whose three values ("0" Off, "1" Normal, "2"
Full) are an enumeration rather than a range; it is stored as an enum so the
panel draws a picker instead of an integer box the description has to explain.
Its default is Normal ("1"). After a power cut or an operating-system crash,
Off can corrupt the whole workspace file, Normal cannot corrupt it but may lose
the last few seconds of writes, and Full keeps every committed write.
proxyMode is the third - see Proxy settings below.
The Settings panel renders entries dynamically, so new keys appear without app
changes. The entries below span three categories: the data_retention keys
govern how much of a run is kept on disk; maxResponseBodyBytes is limits,
because it fails an oversized read in flight and stores nothing; and
phaseHistograms joins the three monitor* keys in observability, which
governs what a run measures rather than what it keeps:
| Key | Default | Range | Effect |
|---|---|---|---|
maxTraceBodyBytes |
5242880 |
1024–104857600 | Largest request/response body stored in a design run's trace_data. Bigger bodies are truncated with bodyTruncated/bodyBytes (see GET /runs/:id). |
maxResponseBodyBytes |
33554432 |
1024–1073741824 | Largest response body a load-test transfer reads into memory, and what a pm.sendRequest from any of that run's scripts (inline step scripts, script.setup / script.teardown, the deferred tests script) may read. A bigger response fails that request (see POST /runs). Not a storage cap and unrelated to maxTraceBodyBytes, which truncates what a completed design request writes to the database. |
maxDesignResponseBodyBytes |
33554432 |
1024–1073741824 | Largest response body a design-mode send - POST /execute, and each step of a collection run - reads into memory, and what a pm.sendRequest from that send's scripts (a collection run's setup and teardown scripts included) may read. A bigger response is read up to this point and answered with bodyCapped: true (see POST /execute) rather than failing, because someone is watching for it - a script's own fetch is the exception and refuses, having no way to tell the script its body was cut (see scripting). Separate from maxResponseBodyBytes above, which is the load path's and refuses in every case. |
maxElementBodyBytes |
1048576 |
1024–1073741824 | Largest response body an extract.json or assert.jsonpath element will parse as JSON, in a design send, a collection run and a scenario load run alike. A bigger response is not parsed at all, instead of paying for - or failing on - a parse of an oversized body, and the step does not pass on it: an assert.jsonpath fails and a required extract.json fails the step, both with the reason, while an optional extract.json reports skipped with it. A body that parses but nests deeper than 100 levels is unreadable the same way, whatever its size, as is one that is not JSON; that depth is fixed, not a setting. The one shared parse per step is reused by every such element, so this is a per-step cost, not a per-element one. |
maxSampleBodyBytes |
32768 |
0–104857600 | Largest response body kept for a single captured load-run sample. Bigger bodies are stored truncated and marked. Deliberately far below maxTraceBodyBytes: a design run stores one exchange the user asked for, a load run stores tens nobody asked for individually. 0 keeps headers and metadata and no body. |
maxSampleBytes |
2097152 |
0–1073741824 | Total captured body bytes one load run may store. Once spent, samples keep their headers and metadata and only their bodies are dropped; the report counts them as sampling.sampleBodiesDropped. |
maxResponseSampleBytes |
268435456 |
0–1073741824 | Total response-body bytes one load run may hold for its post-run test scripts and schema checks. Two orders of magnitude above maxSampleBytes because these bodies are kept whole - a truncated one would fail a check the target passed - so past the budget whole samples are dropped instead, counted as sampling.responseSamplesDropped. 0 retains no sample that has a body. |
phaseHistograms |
true |
boolean | Record DNS/connect/TLS/first-byte/download times for every load-test completion into five HdrHistograms, so the report can carry timingBreakdown.phases percentiles and averages over every completion instead of over the retained trace sample, and the live stream's gate frames can carry cumulativePhases. Costs five atomic histogram writes per completion; see benchmarks. |
maxRunsRetained |
200 |
0–100000 | Keep at most this many most-recent load and collection runs; older ones (and their metrics/results, including captured response bodies) are pruned at startup and after each run finishes. Design Sends are counted under maxDesignRunsRetained instead and never evict these. 0 = unlimited. Captured data is stored verbatim, so this doubles as its expiry. |
maxDesignRunsRetained |
100 |
0–100000 | Keep at most this many most-recent design Sends (POST /execute runs); older ones and their stored exchange are pruned at startup and after each Send. Counted apart from maxRunsRetained, so Sends never evict a load or collection run (#2429). 0 = unlimited. |
runRetentionDays |
30 |
0–3650 | Delete runs older than this many days. 0 = unlimited. |
trashRetentionDays |
30 |
0–3650 | Destroy collections, requests, environments, saved examples and client certificates deleted more than this many days ago, swept at startup. Until then they are restorable - see Trash. 0 keeps the trash forever. |
monitorIntervalMs |
1000 |
250–60000 | Scrape cadence for a monitor block that names no intervalMs of its own. Read per run, so a change applies to the next run started. The bounds on a block's own intervalMs are fixed at 250–60000 either way - they exist to stop a cadence that measures the scraper rather than the target. |
monitorMaxSeries |
8 |
1–64 | How many metric names one run may chart from its monitored endpoint. A longer series list is a 400. Raising it past 4 repeats chart colours (the categorical palette has four line-legible hues). |
monitorScrapeTimeoutMs |
0 |
0–60000 | How long one scrape may take before it counts as a gap. 0 derives it from the cadence in force for that run - three quarters of the interval. Set it explicitly for an exposition that is slow to render: one taking longer than three quarters of the interval fails every scrape otherwise, and the only other way out is a slower cadence, which also thins the data. A value longer than the interval a run scrapes at is shortened to it (logged once per run), because a scrape that outlives its own cadence puts the loop behind itself. |
Proxy settings¶
Four network_performance entries decide how every outbound request
leaves the machine - design sends, load runs, SSE streams, OAuth token
acquisition, POST /import/fetch (which spec re-fetch and $ref bundling ride)
and the monitor scrape alike. They are read at the point of use, so a change
applies to the next transfer with no restart; a load run and a collection run
read the policy once at run start and hold it for the run, because libcurl
reuses a pooled connection only when its proxy configuration matches.
| Key | Default | Values | Effect |
|---|---|---|---|
proxyMode |
environment |
environment, system, manual, off |
Where the proxy comes from. environment is libcurl's own http_proxy / https_proxy pickup - what a terminal-launched engine already got, and what a desktop launch usually inherits nothing of. system uses proxySystemUrl, which the app resolves from the operating system. manual uses proxyUrl. off sends direct and also disables the environment pickup. |
proxyUrl |
"" |
curl-shaped URL | The proxy for manual mode: scheme://user:password@host:port. The scheme selects the kind (http, https, socks4, socks4a, socks5, socks5h, socks5t); a scheme-less host:port means http://. Credentials in the URL become basic proxy authentication; write an @ in the password as %40 (libcurl ends the userinfo at the first @, so a URL with a second one before the host is a 400). An https proxy is verified against the same trust as the target (the platform's anchors plus customCaCertificates) and the request's verifySSL - see TLS trust settings. |
proxySystemUrl |
"" |
curl-shaped URL | The proxy for system mode, written by the app, not typed by the user. The Electron main process resolves the OS proxy through Chromium and stores the answer here at startup, when the machine wakes, and when the renderer sees the network change. Empty means nothing resolved - see the fallback below. Validated exactly as proxyUrl is, under every mode. |
proxyBypass |
"" |
hosts separated by commas, spaces or tabs | Hosts that skip the proxy, passed to curl's NOPROXY. Each entry is an exact host (localhost), .suffix (a domain and everything under it), a bare suffix, an IPv4 or IPv6 address written bare (::1), ip/N CIDR (10.0.0.0/8), or a single * that bypasses everything. A 400 refuses the shapes libcurl would take as a hostname no transfer dials, so the exemption would silently never apply: a :port, a * inside an entry (*.example.com, local*), a bracketed IPv6, a scheme, a path, or a whitespace or control character other than the comma, space and tab separators (a newline). Hostname characters beyond that are not validated. An entry already stored in one of those shapes (a hand-edited row) is left out of what reaches libcurl, with a warning naming it; the other entries stay. |
proxyBypass and an inherited no_proxy interact by mode, deliberately.
libcurl consults the process's no_proxy variable whenever CURLOPT_NOPROXY
is unset, so:
- Under
manual, this list is the entire rule and is always written, empty or not. An empty list exempts nothing, and an inheritedno_proxyis ignored. Anything else means a user who named a proxy in Settings has their traffic silently exempted from it by an ambient variable - which is the same invisible failure the mode exists to fix, and not hypothetical: a container exportingno_proxy=...,127.0.0.1,...bypasses a configured proxy for every local target and says nothing. - Under
environment, an empty list defers tono_proxy- "do what the environment says" includes the exemptions it names - and a non-empty one overrides it. - Under
systemit follows whichever of those two the mode resolved to: themanualrule once a proxy is in force, theenvironmentrule when nothing resolved. - Under
offthere is no proxy for a bypass list to modify.
system mode has two limitations, and both are disclosed rather than
hidden. The engine cannot resolve an OS proxy itself - that answer lives
behind Chromium's network stack, which libcurl sees none of - so the resolution
is the app's and this setting is the channel:
- PAC is resolved once, not per request. A PAC script answers per URL and
the engine cannot call back into Chromium for every transfer, so the app
resolves against one probe URL and that answer applies engine-wide. A
configuration returning different proxies for different URLs needs
manual. - A headless engine falls back to
environment. With no app running,proxySystemUrlis empty andsystembehaves asenvironmentdoes - not asoff, because the environment pickup is the closest thing to "what this machine would do" that a daemon on its own has. An unusable stored value falls back the same way, with the reason logged.
POST /config enforces one cross-field rule these three have and the per-key
validation cannot express: proxyMode: "manual" requires a usable
proxyUrl, judged against the state the update would leave rather than
against the keys in the body, so setting the mode alone is a 400 and so is
clearing the URL while the mode is already manual. A malformed URL is
rejected under any mode; a valid URL stored while the mode is off is kept
untouched, which is how a proxy is switched off temporarily without losing it.
A failure of the proxy hop is reported as its own error code, PROXY_ERROR,
rather than as the target's:
- an unresolvable proxy hostname (previously
CONNECTION_FAILED, which sent people debugging an endpoint that was never reached); - a proxy that is down, so connecting to it is refused (#3257). The refused
socket is the proxy's whatever the target is, and the target was never
dialled. This holds in every mode,
environmentincluded, because the decision reads libcurl's own record that a proxy was in the path (CURLINFO_USED_PROXY) and not the configured URL; the same refusal with no proxy in the path stays the target'sCONNECTION_FAILED; - a SOCKS handshake failure;
- a
4xxanswered to aCONNECT, which anhttps://target makes the proxy see - including the407a proxy demanding authentication returns, which curl reports as a generic receive error and which previously surfaced asINTERNAL_ERROR; - a forwarding proxy's
407on a plainhttp://request (#3257), which needs noCONNECTand so comes back as an ordinary response that read as the server's own answer.POST /execute(and the other single-request sends: the connection test,pm.sendRequest, the OAuth token fetch, the import fetch) reports it asPROXY_ERRORwith status0and the message "The proxy answered 407 Proxy Authentication Required: check the proxy's credentials". A407is the proxy's only when a proxy carried the transfer and no tunnel stands between the engine and the server: a407a server sends directly, or through an establishedCONNECTtunnel, stays a response with its status.
A load run keeps counting a proxy's 407 as a status, as it does any
other status the proxy returns on a forwarded http:// request: the load path
does not reinterpret completed transfers, so the run's status distribution
shows the 407s and its error counts do not. A proxy that is down is
PROXY_ERROR there too, since that mapping reads the failed transfer.
The code is appended to the error enumeration, so the numeric values stored in existing traces are unchanged.
Two more failures of the target's answer have their own codes
(issue #2462): TOO_MANY_REDIRECTS, when the server redirected past the
request's maxRedirects (usually a loop), and BAD_CONTENT_ENCODING, when the
response declares a Content-Encoding that its bytes are not in or that this
libcurl has no decoder for. Both previously came back as CONNECTION_FAILED,
which sent people looking for a network fault when every hop had been answered.
errorMessage opens with a plain statement - Too many redirects: the server
redirected more than N times (see Maximum redirects). Maximum (N) redirects
followed, which is the engine's own text and ends there (the engine follows
redirects itself), or The response could not be decoded: the server sent
Content-Encoding X., which is followed by libcurl's own text. The codes are
appended to the enumeration like PROXY_ERROR, so stored numeric values are unchanged, but a script that tested
err.code === 'CONNECTION_FAILED' (pm.sendRequest) or
pm.response.errorCode === 'CONNECTION_FAILED' for these two failures now sees
the new spelling. A load run records them under the error types
too_many_redirects and bad_content_encoding.
A target that answers in something other than HTTP/1.x is PROTOCOL_MISMATCH
(issue #3306), error type protocol_mismatch. The usual case is an h2c
server (HTTP/2 over cleartext) sent a request over http://: Vayu speaks
HTTP/1.1 there whatever httpVersion says (the Protocol paragraph under
POST /execute), and the server answers with its binary HTTP/2
preface, which libcurl reports as Received HTTP/0.9 when not allowed. That failure used to come back
as INVALID_URL, which sent people to a URL that was fine. errorMessage
opens with The server answered in a protocol other than HTTP/1.x: followed by
libcurl's text, and when the request asked for http2 and the hop that failed
was http:// (after any redirect) it adds HTTP/2 is only negotiated over
https://; this server may speak h2c, which Vayu does not send. A scheme the
transfer refuses, a redirect onto ftp:// included, is still INVALID_URL.
The code is appended like the others, and a script sees it as err.code
(pm.sendRequest) or pm.response.errorCode.
A send still in flight when the engine shuts down is cancelled rather than
waited on (issue #2683), and so is a pm.sendRequest one of its scripts is
making: the send answers, and its trace records, CANCELLED with
errorMessage Request cancelled, about a second after the shutdown began.
A buffered send whose caller hangs up before the answer is cancelled the same
way (issue #3383), together with an OAuth 2.0 token it is fetching and a
pm.sendRequest one of its scripts is making: the engine reads the connection
every 100ms and the transfer ends at its next progress tick, about a second
later. The run is recorded stopped, never completed; its result row
holds what the exchange reached, CANCELLED for a transfer that was cut. A
transient send records nothing, as always. "Hangs up" is the connection reading
end-of-stream, and TCP cannot tell that from a caller that only shut down its
sending side, so a client that half-closes after its request is treated as
gone: keep the connection open until the answer is read. A streaming send
(stream: true) is not watched: it is handed off at its 202 and outlives the
call that started it, and POST /runs/:runId/stop is
what ends it.
Cookies are unaffected by any of this: libcurl owns the wire cookies and matches them on the origin host, never the proxy hop.
Default request headers¶
Five network_performance entries decide what Vayu adds to a request nobody
wrote it into (issue #1229, and #2468 for the Expect header). They are read at the top of a request or a run, so
a change applies to the next send; a load run reads them once at run start, as
it does the proxy policy.
| Key | Default | Values | Effect |
|---|---|---|---|
negotiateCompression |
true |
boolean | Ask for a compressed response on a Send, a collection or scenario run, and a script's own pm.sendRequest. The value advertised is what this libcurl can decode, read off curl_version_info - gzip, deflate plus br and zstd where the build has them - and libcurl decodes the response before the engine sees it. Off sends no Accept-Encoding at all. |
loadNegotiateCompression |
true |
boolean | The same decision for a load run, separate because compression is part of what a load test measures: off measures a server's uncompressed ceiling, on measures what its clients actually get. |
sendExpectContinue |
false |
boolean | Let libcurl send Expect: 100-continue on a large body. libcurl adds that header on its own to an HTTP/1.1 body over 1 MiB (1048577 bytes and up) and then waits about a second for an interim reply a server that ignores the header never sends, so with this off the engine removes it with libcurl's Expect: removal line and the transfer sends the body at once. One key for a Send, a collection run and a load run alike. The removal line is not a sent header, so it is not in requestHeaders. |
correlationIdEnabled |
false |
boolean | Send a header carrying a fresh identifier with every request, so one send - or one iteration of a load run - can be found in a server's log. Off by default: it is a header the target did not ask for. |
correlationIdHeader |
X-Vayu-Request-Id |
header name | Which name that identifier goes out under. Vendor-namespaced by default so it collides with nothing a gateway defines; set it to X-Request-ID or X-Correlation-ID for infrastructure that reads one of those. POST /config refuses a value that is not a header name (RFC 9110 token), because a broken name would otherwise put a broken line on every request afterwards. |
Three rules hold for all of them, and for the User-Agent the engine has always
added:
- A header the request carries wins. Nothing here overwrites a name the
request already names, so a browser's
User-Agent, a hand-typed correlation id, or anAccept-Encoding: identityis sent exactly as written. A request that namesAccept-Encodingitself also gets no decoding: libcurl hands back what arrives, which is what typing that header asks for. - Any of them can be refused per send, with
disabledDefaultHeaderson POST /execute or POST /runs. - None of them is stored. They are applied at send time, so a saved request
cannot carry a stale one. A request saved before this change is stripped of
the rows an older app wrote into it, once, at startup:
X-Vayu-Versionalways, anX-Request-IDwhose value is a bare UUID, and aUser-Agentwhose value is aVayu/.... A correlation id or aUser-Agentsomeone typed is left alone.
The correlation id is generated per transfer, not per composition, so every iteration of a load run carries its own.
Expect is the one default the engine takes away rather than adds. With
sendExpectContinue off, a request that names no Expect gets libcurl's
removal line, whatever its size or verb. A typed Expect: 100-continue is the
way to send one on purpose: it goes out as typed with the key off, and is
recorded in requestHeaders. A typed Expect with a blank value is sent empty,
like any blank row (see requestHeaders), and recorded with
the value ""; libcurl adds no 100-continue of its own beside it, so the body
goes out without the wait and without a removal line. With the key
on nothing is appended, so libcurl decides (over 1 MiB, on HTTP/1.1), and the
Expect row GET /request-defaults declares is the one a send refuses with
disabledDefaultHeaders, which removes libcurl's line again. With the key off
that refusal changes nothing: the line is already removed.
Every size the API reports is the bytes Vayu holds - bodySize, a stored
trace's bodyBytes, a load sample's body_bytes. With negotiation on those are
the decoded bytes, because libcurl decodes before the engine counts; with it
off they are the identity response, which is the same number. What crossed the
network compressed is not measured, and rawRequest is where the negotiated
Accept-Encoding line itself can be read back.
TLS trust settings¶
One more network_performance entry decides who the engine trusts, and it
reaches the same six outbound paths the proxy settings do.
| Key | Default | Values | Effect |
|---|---|---|---|
customCaCertificates |
"" |
PEM text (text entry) |
Certificate authorities to trust in addition to the ones this platform already trusts. Pasted content, not a path: a path breaks when the file moves and cannot be shown back in Settings. POST /config refuses text that holds no -----BEGIN CERTIFICATE----- block, and names a pasted private key for what it is. It then parses every certificate block with OpenSSL and answers 400 naming the first one that does not, counted from 1 (certificate 2 of 3 does not parse); only the parse is asked, never validity or expiry. |
The engine materializes the bundle as ca-bundle.pem beside its database and
points CURLOPT_CAINFO at it, rewriting the file only when the setting's
content changes. A block that does not parse in a value stored before that
check is left out of the file and logged (a warning naming the setting and the
block's position), because OpenSSL abandons a bundle file at its first bad block
and the platform's anchors would go with it. Native trust is preserved - the mechanism differs by TLS
backend, and each is stated rather than assumed:
| Platform | Backend | What the bundle does |
|---|---|---|
| Linux | OpenSSL (default paths + CURL_CA_FALLBACK) |
CURLOPT_CAINFO replaces the default bundle, so the materialized file is the platform's own anchors concatenated with the pasted ones. The system bundle is located the way curl locates it: CURL_CA_BUNDLE / SSL_CERT_FILE, then libcurl's compiled-in cainfo, then the standard distribution paths. |
| macOS | OpenSSL | Same as Linux, and the anchors are read from /etc/ssl/cert.pem and merged into the materialized file. CURLSSLOPT_NATIVE_CA is also set on every macOS handle, pasted CA or not: when a certificate does not verify against the file, the Keychain is asked, so a root or an admin-installed CA the Keychain trusts verifies with nothing pasted. |
| Windows | OpenSSL, selected explicitly (issue #851; Schannel before it) | The anchors live in the certificate store and Windows ships no PEM bundle to merge with, so the materialized file holds the pasted certificates alone and CURLSSLOPT_NATIVE_CA - set on every Windows handle, pasted CA or not - loads the store beside it. A machine that exports CURL_CA_BUNDLE puts a file back in reach and the merge runs there as it does on Linux. |
Three things make that table checkable rather than a claim. The backend column
itself is asserted on each CI platform - both its name and that this process
selected it rather than inheriting whatever libcurl chose - so it is read
off the build rather than out of a port file, the mistake that left the macOS
row wrong until issue #818. The selection is not a formality on Windows: the
curl port's http2 feature depends on curl[ssl], which resolves to Schannel
there, so that libcurl carries both backends and picks between them by reading
CURL_SSL_BACKEND from the environment. The engine names OpenSSL before curl
initializes, which is what stops a stray environment variable from moving every
request onto a backend where client certificates do not work at all. Issue #858
tracks getting Schannel out of the build entirely.
CURLOPT_CAINFO is the one transport option a backend can refuse outright, so
the engine checks the return code and logs an error naming the backend if it
ever does - and the test suite asserts on every CI platform that this build's
backend accepts it. And where the anchors come from a file, the suite asserts
they were actually found; where they come from the store, that the build accepts
the flag that loads it. Either way a merge with nothing to merge would narrow
trust to the pasted certificate alone while this page still promised the
opposite, so NativeStoreVerificationTest closes it on a wire: a public
certificate has to verify with nothing pasted, and go on verifying once an
unrelated CA is.
CURLSSLOPT_NATIVE_CA asks the backend to keep consulting the OS store. It is
set unconditionally on Windows, where it is the anchor source, and on macOS,
where the Keychain backs the file; on Linux it is set whenever a bundle is in
force, and the merge above is what carries the guarantee.
What the Windows certificate store does not give you. OpenSSL reads it through the Windows crypto API rather than being the OS verifier, so three things Schannel did on its own do not happen:
- Root certificates only. Intermediates cached in the store are not
supplied to the chain builder (curl 12155), so a server that does not send
its full chain can fail on Windows where it verified before. Pasting the
intermediate into
customCaCertificatesfixes it. - No on-demand root fetch. Windows can download a missing trusted root when Schannel asks for one; nothing here asks, so only roots already in the store count.
- No revocation through the store. Schannel passed
CERT_CHAIN_REVOCATION_CHECK_CHAIN; OpenSSL does not revocation-check the chain unless told to, and the engine does not tell it to on any platform - so Windows now behaves like Linux and macOS here rather than being the strict one.
A certificate that still fails to verify fails at handshake time with libcurl's
own SSL_ERROR - the validation on the way in is about the shape of the
paste, deliberately, so a chain curl would accept is never refused by a parser
of ours.
A TLS connection that never answers is an SSL_ERROR too, whatever code
libcurl put on it. The mapping needs that rule because the interesting
refusals do not arrive as TLS errors: under TLS 1.3 the server's verdict about
the client - a certificate it will not accept, or one it demanded and did not
get - reaches us after our own handshake has finished, so libcurl reports the
generic receive error of a connection that went away, carrying the alert in its
message. A key the stored passphrase does not open arrives as a generic
argument error in the same way. All three used to surface as INTERNAL_ERROR,
which says the failure was ours. The rule applies only where the mapping has no
answer of its own, and only to an https transfer that produced no response
line at all - so a 4xx, a timeout, a refused connection and a proxy failure
all keep the code they had (issue #802).
Per-request, verifySSL: false turns verification off for one endpoint
entirely (see POST /execute); trusting the authority here is
the answer that keeps verification on everywhere else.
An https:// proxy is a second TLS handshake with the same trust. libcurl
decides the proxy's certificate with options of its own
(CURLOPT_PROXY_CAINFO, CURLOPT_PROXY_SSL_OPTIONS,
CURLOPT_PROXY_SSL_VERIFYPEER / _VERIFYHOST) that do not inherit what the
target's handshake was given, so the engine writes each of them from the same
values as its target-side twin: a proxy whose certificate a pasted authority
signed verifies, and verifySSL: false covers the proxy leg as well as the
target. No client certificate from the registry is ever offered to a proxy - an
entry names a host the user trusts with that identity, and a proxy is not it. A
proxy certificate that is refused is an SSL_ERROR whose message says the
proxy's certificate was not accepted, so the target's is not blamed.
In-progress (running/pending) runs are never pruned, and neither are runs
pinned as baselines (see
PUT /runs/:runId/baseline); neither kind counts
toward maxRunsRetained or maxDesignRunsRetained. Each cap counts only its
own kind: load and collection runs under maxRunsRetained, design Sends under
maxDesignRunsRetained; runRetentionDays applies to every kind.
GET /request-defaults¶
What the engine will add to a request that names none of it - the set a client renders beside the request's own headers instead of re-deriving it from the config entries above.
{
"headers": [
{ "name": "User-Agent", "value": "Vayu/0.25.0", "generated": false },
{ "name": "Accept-Encoding", "value": "gzip, deflate", "configKey": "negotiateCompression", "generated": false },
{ "name": "X-Vayu-Request-Id", "generated": true, "configKey": "correlationIdEnabled" },
{ "name": "Expect", "value": "100-continue", "configKey": "sendExpectContinue", "generated": false }
]
}
The Expect row appears only while sendExpectContinue is on, under both
scopes, and describes what libcurl may send above 1 MiB rather than a header on
every request.
A default that is switched off is absent rather than listed as disabled.
generated: true means the value is made per send, so the row carries no
value at all - an empty string would be a value a client would print.
configKey names the setting that governs the row, and is absent for the
User-Agent, which is always added.
?scope=design|load names the send the answer describes, and defaults to
design. Compression is the one default the two resolve differently: a design
send (a Send, a collection run, a script's own request) reads
negotiateCompression and a load run reads loadNegotiateCompression, so with
the two disagreeing the Accept-Encoding row is present under one scope and
absent under the other. A scope that is neither is refused with 400 and code
invalid_scope rather than served the design answer, which would describe a
run the caller is not asking about; an empty ?scope= is absent rather than a
scope of "", and answers for design.
POST /config¶
Update one or more configuration entries. Two body shapes are accepted:
Batch - update several keys at once:
Single - update one key:
In both shapes, non-string values (numbers, booleans) are coerced to strings.
Each key is validated against its registered type and, for integer / number
entries, its min/max range; boolean entries must be "true" or "false";
enum entries (e.g. defaultHttpVersion) must equal one of that entry's stored
options values. "Unknown" means outside this engine's own catalogue (see
GET /config) - a stored row from a different engine's build
does not make a key known to this one. Validation is all-or-nothing: if any
key is unknown or out of range, nothing is applied and the response is 400
with the specific reason(s):
A body that does not parse, or nests deeper than 128 levels (see
Request bodies), is a 400 with the same code.
Success response: 200 - the full updated entries array (same shape as
GET /config) plus "success": true.
The validation and the write are one lock scope, and the write is one
transaction (issue #1453): a reader (GET /config, or an internal reader
like the proxy policy resolver that reads proxyMode and proxyUrl as two
separate calls) can never observe some of a batch's keys applied and the rest
still stale, and a failure partway through the write leaves every row
unchanged rather than the ones written before it.
Workspace¶
POST /workspace/backup¶
Write one compacted snapshot of the workspace database into
backups/ beside it, then prune older snapshots to maxBackupsRetained
(issue #987). Takes no body.
{
"path": "/home/someone/.local/share/vayu/db/backups/vayu-20260827-124932-118.db",
"sizeBytes": 2097152,
"createdAt": 1787745600000,
"pruned": 1
}
| Field | Meaning |
|---|---|
path |
The snapshot written. The whole point of the response: restoring is a file copy you perform yourself |
sizeBytes |
Its size on disk. A compacted copy, so smaller than the live database |
createdAt |
When it was taken, epoch milliseconds - the stamp its file name carries |
pruned |
How many older snapshots retention removed in the same call |
It runs SQLite's VACUUM INTO, which is why it is safe while the engine is
working. Copying vayu.db by hand is not: the -wal beside it holds
committed transactions the main file does not, so a hand copy is a database
missing its most recent writes. VACUUM INTO reads one consistent snapshot and
writes a defragmented database complete on its own, and is read-only with
respect to the workspace.
A second backup while one is running is a 409. Two concurrent copies would
each write a whole second database - unbounded disk for a button someone
double-clicked - and the second would race the first's retention pass. Anything
else that goes wrong is a 500 naming what SQLite or the filesystem refused;
there is no success response with an empty path.
Retention only removes files Vayu wrote: this endpoint's vayu-<stamp>.db,
and the vayu-<stamp>-pre-v<N>.db an update saves before it migrates the
workspace, which counts toward the same maxBackupsRetained
(db-schema.md). A copy
you put in that directory yourself is left where it is. 0 keeps every
snapshot.
There is deliberately no restore endpoint. A running engine overwriting the database file it holds open is the failure this feature exists to prevent. Restore by hand with the engine stopped - see architecture.md.
Collections¶
Collections are folders that organize requests in a hierarchy.
GET /collections¶
List all collections, ordered by order, then createdAt, then id (see
Ordering); nothing in the trash.
Query Parameters:
- q, limit, offset (optional): one page of the collections whose name
holds q, in the {data, pagination} envelope - see
Paged lists. A bad limit or offset is a 400
(invalid_limit, invalid_offset).
Response (none of the three):
[
{
"id": "col_1234567890",
"name": "My API",
"parentId": null,
"variables": {},
"order": 0,
"createdAt": 1234567890
}
]
POST /collections¶
Create a collection. Create only - see Resource writes for the shared contract and the null-vs-absent rule.
Request:
{
"name": "My API", // Required, no default (null is a 400)
"parentId": null, // Optional, null or "" for root (stored as null); a trashed collection is a 409
"order": 0, // Optional, 0..2147483647; appended after siblings if omitted - see Ordering
"variables": {}, // Optional, collection-scoped variables
"auth": {"mode": "none"}, // Optional, default none; never mode "inherit" - see Collection auth
"dataSchema": {}, // Optional, the declared data contract - see below
"openapi": {}, // Optional, the bound spec document - see below
"specFile": {}, // Optional, the bound spec file - see below
"dataFile": {} // Optional, the bound data file - see below
}
Response: The created collection object, carrying the engine-generated id.
Errors: 400 if the body carries an id
(the engine owns it), if name is missing or
null, if name is empty or whitespace-only (#3253), if a
variables key is blank or padded
(#3251), if auth states mode inherit
(#3445) or a mode outside the
known set, if an openapi binding names no stored spec
(below), if parentId is neither a string nor null
(Accepted field shapes), if order is not an integer
from 0 to 2147483647 or an append finds no slot left
(Ordering), or on a cycle (below); 409 if parentId names a
collection in the
trash (below); 413 naming the field, its size and the cap,
when a serialized variables / auth / dataSchema / openapi / specFile /
dataFile is over the engine's
field cap, or a file binding's
path or fileName is over its own (below).
A storage failure answers 507, 503 or 500, never 400 - see
A storage failure is not a 400.
PUT /collections/:id¶
Update an existing collection. Update only - a 404 when the id does not
exist, never a silent create. The body is a merge-patch: an omitted field keeps
its value, an explicit null resets it to the default.
Request:
{
"name": "Renamed", // Optional; null is a 400 (no default)
"parentId": null, // Optional, null or "" moves it to the root; a trashed collection is a 409
"order": 3, // Optional, 0..2147483647; a move with no order appends - see Ordering
"variables": null, // Optional, null resets to {}
"auth": null, // Optional, null resets to {"mode":"none"}; never mode "inherit" - see Collection auth
"dataSchema": null, // Optional, null clears the declared contract
"openapi": null, // Optional, null or {} unbinds the spec document; nothing else
"specFile": null, // Optional, null unbinds the spec file
"dataFile": null // Optional, null unbinds the data file
}
A parentId that changes the collection's parent and states no order appends
the collection among its new siblings, rather than carrying a position from the
list it just left. See Ordering.
A parentId that takes the collection out of the spec contract that answers
for the requests beneath it is removing them from that contract (#3470), the
rule PUT /requests/:id applies to one request, with the
same meaning of out: every request in the subtree that records an operation
(specOperation) and whose nearest binding after the move names another
document, none, or the same document from a collection outside the source's
contract has its stamp cleared, and the operation is recorded as declined
under the binding it left, in the same transaction as the collection's own
row, so the source's POST /specs/diff lists it under
declined rather than added. The binding after is read against the tree the
PUT writes, so an openapi: null in the same body counts: a bound
collection unbound and moved out at once clears its requests' stamps, and the
decline that records under it is forgotten with the binding's other records
(below). A move within one contract keeps every stamp, and so does moving the
bound collection itself. The response is the collection; the cleared requests
are read back with GET /requests/:id or arrive on the
change feed. This is the decline
POST /reorder records for a moved folder.
Headers: If-Match (optional), see
Conditional updates.
Response: The updated collection object, with its ETag.
Errors: 404 if the collection does not exist; 412 if If-Match no
longer names the stored row; 400 on a null or empty or whitespace-only
name (#3253), a malformed If-Match,
a blank or padded variables key (#3251), an
auth that states mode inherit (#3445) or a mode outside
the known set, an
openapi that is neither null nor {} (binding is
POST /specs/bind, issue #3348, below), a parentId
that is neither a string nor null
(Accepted field shapes), an order
that is not an integer from 0 to 2147483647 or an append with no slot
left (Ordering) or on a cycle
(below); 409 if parentId names a collection in the
trash (below); 413 naming the field, its size and the cap, when a
serialized variables / auth / dataSchema / openapi / specFile /
dataFile is over the engine's
field cap, or a file binding's
path or fileName is over its own (below).
A storage failure answers 507, 503 or 500, never 400 - see
A storage failure is not a 400.
Cycle validation (both verbs): parentId is validated to keep the
collection tree acyclic, since a
cycle would make the cascade delete below loop forever. Both cases return 400:
parentIdequal to the collection's ownid- messageA collection cannot be its own parent.parentIdpointing at one of the collection's own descendants (a reparent that would form a cycle) - messageCannot move a collection into its own descendant.
Parent existence is intentionally not checked: the import orchestrator creates collections in bulk, so requiring the parent to exist first would couple to import ordering. Only self-parent and descendant cycles are rejected.
A parent in the trash (both verbs) is a 409, message
Collection '<id>' is in the trash - restore it first (issue #1883). That is
different from a parent the store has never seen: a trashed parent would leave
the collection live but invisible under it, and a purge of the parent would then
re-parent it to the root. Only a parentId the body states is checked, so a
PUT that does not move the collection is never refused by its stored parent.
dataSchema (both verbs, and POST /import/apply): the data contract the
collection declares - which columns its data files carry, so {{data.column}}
and pm.iterationData can be checked before a run (issue #599).
{} means the collection declares no contract, and is what an absent field on
create and an explicit null on update both resolve to. A present value must be
an object (400 otherwise, like variables and auth), and its contents are
validated: columns an array of unique, non-empty strings - at most 1024 of
them, each at most 256 characters - declaredAt a number, fileName a string.
Each violation is a 400 naming the field (Invalid 'dataSchema.columns': ...)
that writes nothing.
The schema is stored; the file's rows are not, anywhere. Where the file is
lives in dataFile, below. See Data-driven runs.
openapi (POST /collections, POST /import/apply, and unbinding on
PUT): the OpenAPI document this collection is bound to (issue #637).
{} means bound to nothing, and is what an absent field on create and an
explicit null on update both resolve to. A present value must be an object
(400 otherwise, like variables and dataSchema). A non-empty one is a
binding and is validated further: specId must be a non-empty string that
resolves to a stored spec document (400 naming the id otherwise).
PUT /collections/:id only unbinds (issue #3348): {"openapi": null} and
{"openapi": {}} both store {}, and any other value is a 400 that names
POST /specs/bind, after the 404 and 412 checks. Binding
or rebinding an existing collection restamps every request beneath it both
ways, which only that route does, in one transaction. Unbinding forgets the
operations deletes declined under the old document (issue #3031; see
DELETE /requests/:id).
specHash records which version of the document the collection was last synced
to; a scenario run of a bound collection stamps both values into its snapshot and
report (see GET /runs/:runId/report).
Send the specId; the engine writes the rest (issues #709, #3348): a create
stamps specHash from the document the id names and syncedAt from the moment
of the write, so a binding cannot be stored without the version that contract
coverage and response-schema validation compare against. A specHash or
syncedAt the body sends is dropped, never stored: the version is the
document's, not the caller's claim about it. A collection's recorded version can
still fall behind its document's (a binding an older engine wrote); a run of it
reports hash_mismatch, and a PUT that says nothing about openapi leaves it
as it is.
Deleting the document is refused while a collection binds it - the binding is never cascaded away, see DELETE /specs/:id.
specFile and dataFile (both verbs; refused by POST /import/apply): the
files this collection's Spec and Data tabs are bound to (issue #2765), stored so
a workspace backup carries them.
{"path":"/home/me/specs/pets.yaml","fileName":"pets.yaml"}
{"path":"/home/me/data/users.csv","fileName":"users.csv","hash":"<hex sha256>","castNumbers":true}
{} means no file, and is what an absent field on create and an explicit null
on update both resolve to, so unbinding is {"specFile": null}. A present value
must be an object (400 otherwise). A non-empty one must carry path and
fileName as non-empty strings and no member beyond its own: specFile holds
those two, dataFile adds an optional hash (64 lowercase hex characters, the
SHA-256 of the file's bytes, the digest a run records as dataFileHash) and an
optional boolean castNumbers. Each violation is a 400 naming the field or
member that writes nothing; a path over 96 KiB or a fileName over 1 KiB is a
413 naming the member, its size and the cap. The path's form is not checked: it
is the location on the machine that picked the file, so a Windows path is stored
on Linux as written. A stored path grants nothing - a request body may send a
file only under the file trust rule - and the engine never opens
either file. Neither field appears in POST /export/postman or
POST /specs/export. A POST /import/apply collection item carrying either is a
400 with error.item, because an import describes a document from elsewhere;
null passes.
DELETE /collections/:id¶
Delete a collection and all its requests (cascading delete). The delete is
soft (issue #988): the collection and every descendant are stamped
deleted_at in a single transaction rather than removed, which is why every
read surface stops returning them while GET /trash still can.
The walk terminates even if the stored parent_id tree contains a cycle (see
db-schema.md - collections).
Restore it with POST /trash/:id/restore; destroy it
for good with DELETE /trash/:id, which is also what the
startup sweep does once trashRetentionDays has passed.
Beneath a bound collection, the delete declines operations (issue #3031),
as DELETE /requests/:id does for one request: each
request it stamps that records an operation is recorded under the nearest bound
ancestor, in the same transaction. Deleting a tag folder is the user declining
everything in it. Deleting the bound collection itself records nothing - that
is the whole contract going, not a choice about any operation of it - and a
purge of a bound collection takes its records with it.
The delete stops every running mock of what it trashed
(issue #3449): a mock of the collection itself or of any folder under it,
whichever client sent the delete, before the response is sent, so it is gone
from GET /mock by then. A mock of a collection outside the
subtree keeps running. Restoring the collection does not start its mock again;
POST /mock/start does.
Response:
Requests¶
GET /requests¶
List requests in a collection, or in every live collection. Results are
ordered by order, then createdAt, then id - the same contract
GET /collections has for collections. See Ordering for why the
tiebreak is part of the contract.
Query Parameters:
- collectionId (optional): Collection ID to fetch requests from. Absent, the
response is every live request of every live collection, grouped by
collectionId and ordered within each group exactly as that collection's own
list is - nothing in the trash.
- fields (optional): summary answers each row cut to the keys a tree is
built from (#2546), described below; absent (or empty), the full request
objects. Any other value is a 400 with code invalid_fields, never the
full list. The app builds its whole tree at launch from one
GET /requests?fields=summary call.
- q, limit, offset (optional): one page of the rows whose name holds
q, in the {data, pagination} envelope - see Paged lists.
Each data row is the row the list would have carried, in the shape fields
names, and collectionId scopes it as above. A row that fails to serialize
is skipped (as it is in the bare list) and is not counted in total. A bad
limit or offset is a 400 (invalid_limit, invalid_offset); a bad
fields is refused first.
Summary response (fields=summary): the same rows in the same order as
the full form, each carrying exactly id, collectionId, name, method,
url, order, createdAt and specOperation, spelled and valued as the full
row writes them (specOperation is the object or null). Nothing else is read
from the database, so a large body, header set, auth block or element list
costs its row nothing, and no row carries truncatedFields.
[
{
"id": "req_1234567890",
"collectionId": "col_1234567890",
"name": "Get Users",
"method": "GET",
"url": "{{baseUrl}}/users",
"order": 0,
"createdAt": 1234567890,
"specOperation": null
}
]
Response (no fields): An array of request objects, each in the same shape as a
GET /requests/:id response: params/headers are arrays of
{key, value, enabled} entries and body is a JSON discriminated union
(see the requests table in db-schema.md) - with one
deliberate exception (issue #1485): a row whose params / headers / body
/ auth is over the engine's field cap
carries that field's documented default here instead of the stored value, and
names which fields were substituted in truncatedFields (omitted when
nothing was). GET /requests/:id never substitutes - it answers with the
field whole, however large.
[
{
"id": "req_1234567890",
"collectionId": "col_1234567890",
"name": "Get Users",
"description": "",
"method": "GET",
"url": "{{baseUrl}}/users",
"order": 0,
"params": [{ "key": "page", "value": "1", "enabled": true }],
"headers": [{ "key": "Accept", "value": "application/json", "enabled": true }],
"body": { "mode": "none" },
"bodyType": "none",
"auth": { "mode": "inherit" },
"elements": [],
"followRedirects": true,
"maxRedirects": 10,
"timeout": null,
"httpVersion": "auto",
"verifySSL": true,
"stream": false,
"disableCookies": false,
"disabledSystemHeaders": [],
"disableUrlEncoding": false,
"postmanProtocolBehavior": null,
"updatedAt": 1234567890,
"createdAt": 1234567890
}
]
followRedirects / maxRedirects / httpVersion / verifySSL / stream are
the request's stored execution options. They are always present in the response:
a request saved before these columns existed reads back as the engine defaults
(true / 10 / "auto" / true / false), which is the behaviour it already
had.
timeout is the request's own timeout in milliseconds (issue #2937), always
present on a stored-row response (GET /requests, GET /requests/:id and the
POST / PUT answers): a number, or null when the request states none and sends with
the defaultTimeout setting.
disableCookies / disabledSystemHeaders / disableUrlEncoding are Postman's
per-request protocol settings (issue #1765), always present too (false / [] /
false for a request that states none); postmanProtocolBehavior is the
imported Postman object they came from, null when there is none - see
POST /requests.
httpVersion is "auto" | "http1.1" | "http2" - what was requested, not
what was negotiated; see POST /execute for the negotiated
value on a response.
GET /requests/:id¶
Fetch a single request by id, in one lookup. The app uses this to load a restored request tab or a design-run copy on cold start, instead of fetching every collection's request list and scanning them for the id.
Path Parameters:
- id (required): The request ID to fetch
Response: The request object, in the same shape as a full GET /requests
list entry, with its ETag (W/"<updatedAt>", see
Conditional updates).
{
"id": "req_1234567890",
"collectionId": "col_1234567890",
"name": "Get Users",
"description": "",
"method": "GET",
"url": "{{baseUrl}}/users",
"order": 0,
"params": [],
"headers": [],
"body": { "mode": "none" },
"bodyType": "none",
"auth": { "mode": "inherit" },
"elements": [],
"followRedirects": true,
"maxRedirects": 10,
"httpVersion": "auto",
"verifySSL": true,
"stream": false,
"createdAt": 1234567890,
"updatedAt": 1234567890
}
404 when the request genuinely does not exist. This is distinct from a
5xx: the caller relies on that difference to tell a real deletion from an
unreachable engine, and must not treat a transport failure as "deleted".
POST /requests¶
Create a request. Create only - see Resource writes for the shared contract and the null-vs-absent rule.
Request:
{
"collectionId": "col_1234567890", // Required, no default (null is a 400)
"name": "Get Users", // Required, no default (null is a 400)
"method": "GET", // Required: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
"url": "{{baseUrl}}/users", // Required, no default (null is a 400)
"params": [], // Optional, array of {key, value, enabled, in?, valueless?};
// derived from `url`'s query when absent - see below
"headers": [], // Optional, array of {key, value, enabled}
"body": {"mode": "none"}, // Optional, request body
"bodyType": "none", // Optional, mirrors body.mode - see The request body union
"auth": {"mode": "inherit"}, // Optional, default {"mode":"inherit"}; mode must be a known one - see Auth modes
"elements": [], // Optional, typed behaviours - see Elements. The only
// script source; preRequestScript/postRequestScript/tests
// are refused (400, naming "elements")
"order": 0, // Optional, 0..2147483647; appended after the collection's
// sub-collections and requests if omitted - see Ordering
"followRedirects": true, // Optional, follow 3xx responses. Default true
"maxRedirects": 10, // Optional, hops while following, clamped to 0..100. Default 10
"timeout": null, // Optional, this request's timeout in ms, 1..86400000.
// Absent/null: the "defaultTimeout" setting - see below
"httpVersion": "auto", // Optional: "auto" | "http1.1" | "http2". Absent/null seeds
// from the "defaultHttpVersion" config entry
"verifySSL": true, // Optional, verify the TLS certificate. Default true
"stream": false, // Optional, consume the response as an event stream.
// Default false - see below
"specOperation": null, // Optional, which spec operation this request is - see below
"methodSource": null, // Optional, which app setting wrote `method` - see below
"mockResponseMode": "first", // Optional: "first" | "fixed" | "random". Default "first"
// - which saved example a mock server answers with, see below
"mockExampleId": null, // Optional, the example id `mockResponseMode: "fixed"` targets
"disableCookies": false, // Optional, keep the cookie jar out of this request. Default false
"disabledSystemHeaders": [], // Optional, header names the engine does not add. Default []
"disableUrlEncoding": false, // Optional, send the URL as typed, with no percent-encoding.
// Default false
"postmanProtocolBehavior": null // Optional, the imported Postman object - see below
}
A query row in params describes the query in url; url is the wire
truth. Nothing in the request-composition path reads a query row, so a query
parameter that must reach the wire belongs in url: a caller that puts the
query only in params stores a request that sends none of it (issue #590).
The write keeps the rows in step with the URL (issue #3551). A POST or PUT
that states url and no params has its query rows reconciled with the
URL's query, the rule the app's Params table follows on every URL keystroke
(mergeParamsFromUrl):
- each enabled row claims the first unclaimed pair whose key its own key
writes (under any of the query joins, so an OpenAPI import's
a bclaimsa%20b), rows in stored order, and the merged rows follow the URL's pair order; - a claimed row keeps every other member (
description,source, ...); one that no longer writes its pair takes the pair's key and value, andvaluelessfollows the pair (truefor a barekeywith no=); - a pair no row claims becomes a fresh
{key, value, enabled: true}row (plusvalueless: truefor a barekey), and an enabled row the URL no longer carries is dropped; - a disabled row is kept, after the nearest enabled row before it that the URL still carries, or first when there is none; path rows are left untouched.
Rows that already state the URL's query are left byte for byte, so a host or
path edit sent as url alone rewrites nothing. A body that states params
stores them as sent, whatever url says, and a body that states neither keeps
the stored rows. POST /import/apply and POST /specs/sync reach the same
applier: a sync update that applies a request's url without its params
reconciles the kept rows with the new URL's query. So a request created from a URL alone (every MCP request)
reads back with one row per query pair, and the
OpenAPI export, the spec diff and the
Postman export see its query. Rows stored before the
rule are not rewritten until their next URL-only write, so the Postman export
still writes a URL pair no enabled row states into url.query[] (issue
3242), and the app still merges a URL-only query into the Params table when¶
it opens one, without marking the tab unsaved (issue #3491).
A path row is the one row composition reads (issue #1764). A row carrying
"in": "path" is a Postman-style path variable: key is the name without its
colon, and the URL keeps the :name segment verbatim
({{baseUrl}}/users/:id). POST /compose writes the row's
value in place of the segment at send time - see
Path variables there. A row with in absent, "query" or
anything else is a query row, and everything that joins or splits the query
(the importers' URL join, the Postman and OpenAPI exports) skips path rows.
The field needs no schema change: rows are stored verbatim, extra keys
included.
stream is the saved half of POST /execute's stream
(issue #574). It records that this endpoint is a text/event-stream, which is
a property of the endpoint rather than of one send, so the app's Event stream
toggle persists here and a bulk import carries it. The engine never acts on the
stored value by itself: POST /execute reads the flag off the payload it is
given, and the by-id compose path deliberately does not add it, so an existing
caller that composes by id keeps getting a buffered send.
timeout is the saved half of POST /execute's timeout
(issue #2937): one slow endpoint can wait longer, or a fast one fail sooner,
without changing the defaultTimeout setting for every request. It is held to
the same 1-86400000 ms, and a number outside it or a value that is not a
number is a 400 naming 'timeout' here, on PUT and in POST /import/apply.
Absent or null on create stores none, and the request sends with the setting
in force at each send rather than a copy of it. POST /compose
by requestId emits timeout only when the request states one, so a Send, a
sequential collection run, a single-request load run built from the composed
payload and a scenario load step all take it, and a request that states none
still takes the setting. A Postman collection has no per-request timeout, so
POST /export/postman lists one under notCarried (request_timeout); an
OpenAPI export carries it in x-vayu-request.settings.
specOperation names which operation of the collection's
bound spec this request is (issue #637):
method and path are required inside the object and operationId is optional,
because an OpenAPI operation may declare none. path is the templated path
from the document, never a concrete URL - it is the identity a re-fetched spec is
diffed against - so a path that does not start with / is a 400, as is a
missing or empty method / path, a non-object value, or a non-string
operationId. null (or absent on create) means the request declares no
operation, and both request serializers emit specOperation: null for it - the
key is always present, so a client never has to tell "no operation" from "not
serialized". Two requests may name the same operation.
methodSource names which app setting last wrote method, still unclaimed by
the user (issue #1505). The only value a client writes is "graphql" - the
GraphQL body mode setting method to POST on a fresh GET - and null (or
absent on create) means no marker: either the user chose method themselves, or
nothing has set it. "graphql" is the only accepted value; anything else is a
400. The app clears the marker itself the moment method is written by
anything other than the GraphQL switch, so a method the user has since picked is
never reverted - the same "still ours" contract KeyValueEntry.source (issue
1481) gives a header row.¶
mockResponseMode names which saved example a mock server answers with
(issue #481 phase 3): "first" (the default, absent or null on create both
mean this), "fixed" (the example named by mockExampleId) or "random".
Anything else is a 400, the same way an unrecognized methodSource is.
mockExampleId follows the same null-vs-absent rule as specOperation: absent
keeps the current target, null clears it, and a non-empty string sets it -
it is not checked against the request's saved examples at write time, because
the target can be created afterwards or deleted later, and a mock server falls
back to "first" for either case rather than this write refusing one up front.
Deleting the target through DELETE /requests/:id/examples/:exampleId clears
mockExampleId to null (issue #3422) and leaves mockResponseMode as it was;
restoring the example from the trash does not set it again.
Postman's per-request protocol settings (issue #1765), under the same
null-vs-absent rule (absent keeps on update, null resets):
disableCookieskeeps the cookie jar out of every send of this request: no jar cookie is attached and noSet-Cookieis stored. ACookieheader the request carries still goes out, and a pre-request script'spm.cookies.jar()write is still persisted. With the jar on, a typedCookieand the jar's matches go out as oneCookieline, the jar's first, never as two (issue #2788). The one case it does not go out is a jar line that reaches libcurl's 8190-byte limit: libcurl drops the typed rows with the jar cookie it leaves off, and the answer says so underwarnings(cookie_not_sent, issue #3307).disabledSystemHeadersnames headers the engine does not add on its own. It is stored lowercased and deduplicated in first-appearance order, and unioned on every send with the per-senddisabledDefaultHeaders(see POST /execute):user-agent,accept-encodingand the correlation id as that list refuses them,acceptremoves libcurl's implicitAccept: */*,content-typeremoves the Content-Type a body implies (multipart keeps its boundary header), and with it aContent-Typeheader row marked"source": "body-mode"- the row the app's Body panel writes and the importer adds for a GraphQL, JSON-RPC or XML body, which is the body's own header, not the user's. AContent-Typerow without that marker is the user's and is always sent. Other names (host,content-length,postman-token, ...) are stored for the export and change nothing on the wire.disableUrlEncodingwrites the URL as typed rather than percent-encoded: a path variable's value skips Postman's path encode set, an api-key (or OAuth 2.0 query-placed) credential and a substituted{{variable}}skip their rules, and the rest of the URL is not rewritten either (Query encoding), soa"bgoes out asa"b, nota%22b, as Postman'stoNodeUrl (url, disableEncoding)sends it. With encoding on, a raw space is percent-encoded to%20; with the toggle on it is refused, and the send fails with a message that names the space and the toggle (URL schemes).postmanProtocolBehavioris the Postman item'sprotocolProfileBehavior, kept for POST /export/postman and sent by nothing. It takes an object or a string holding a JSON object; the string is the spelling the importer writes, because it keeps the source's member order (an object crossing the engine's reader does not).GETanswers it as that stored text, a string (ornull), the way it is written: a client that sends the record back, as the app's Duplicate does, stores the same bytes, and the copy exports the sameprotocolProfileBehavior. The string is read again by the engine, so it is held to the request-body depth bound too (see Request bodies): a string nested deeper than 128 levels is a400.
A non-boolean disableCookies / disableUrlEncoding, a
disabledSystemHeaders that is not an array of header-name tokens, or a
postmanProtocolBehavior that is not an object, such a string or null is a
400 naming the field, as is a postmanProtocolBehavior string nested deeper
than 128 levels (Invalid 'postmanProtocolBehavior': nested deeper than 128
levels); the last two are 413 over the field cap. POST /import/apply answers
the same 400, with the item's tempId under error.item, and writes
nothing.
Response: The created request object, carrying the engine-generated id.
Errors: 400 if the body carries an id
(the engine owns it), if a
required field is missing or null, if collectionId names a collection that
does not exist (message Collection '<id>' does not exist), on an unrecognized
method, on a
params / headers entry that is not {key: string, value: string, enabled: bool},
on a methodSource that is not "graphql" or null,
on a mockResponseMode that is not "first" / "fixed" / "random",
on a mockExampleId that is not a non-empty string or null,
on an order that is not an integer from 0 to 2147483647 or an append
that finds no slot left (Ordering),
on an auth whose mode is not a known one (#3464),
or on an httpVersion that is not "auto" / "http1.1" / "http2" (the body
names the field and lists the valid values); 413 naming the field, its size
and the cap, when a serialized params / headers / body / auth is over
the engine's field cap (issue #1485, see below).
A storage failure answers 507, 503 or 500, never 400 - see
A storage failure is not a 400.
Unlike a collection's parentId (which may name a collection not written yet,
though not one in the trash), a request's collectionId must resolve to
a stored collection. A request under no collection is unreachable: no
per-collection GET lists it, and no cascade delete ever reaps it. Bulk import
is unaffected - POST /import/apply resolves owners from the payload's own temp
ids before any row is written.
PUT /requests/:id¶
Update an existing request. Update only - a 404 when the id does not
exist, never a silent create. Merge-patch body, same rule as collections.
Request: any subset of the POST /requests fields, minus id (it is the
path). Sending collectionId moves the request to another collection; the id
must resolve to a stored collection (400 otherwise), and a move that states no
order appends in the destination - see Ordering. An update that
states no collectionId is not checked against the request's stored one, so a
row stranded before this validation existed stays editable, and repairable by a
PUT that moves it somewhere real. A move that takes a request recording an
operation (specOperation) out of the spec contract that answers for it is
removing it from that contract (#3446): out means the destination's nearest
binding names another document, none, or the same document from a collection
outside the source's contract (a sibling root bound to it too). The operation
is recorded as declined under the source binding, as
DELETE /requests/:id records it, and the stamp is
cleared in the same write, so the source's POST /specs/diff
lists it under declined rather than added. A move within one contract keeps
the stamp, a move between the bound collection and a sub-collection bound to the
same document included; a body that states specOperation beside the move
keeps the stated value. Omitting followRedirects / maxRedirects /
timeout / verifySSL / stream / specOperation / methodSource /
mockResponseMode / mockExampleId / disableCookies /
disabledSystemHeaders / disableUrlEncoding / postmanProtocolBehavior
leaves the stored values untouched; sending null resets them to true / 10
/ "the defaultTimeout setting" / true / false / "no operation" / "no
marker" / "first" / "no target" / false / [] / false / "none".
A non-boolean followRedirects, verifySSL or stream, or a non-integer
maxRedirects, is ignored rather than rejected. maxRedirects is clamped to 0..100 on the way in.
timeout is the exception among them: a value outside 1-86400000 or one
that is not a number is a 400 naming 'timeout', and nothing is written.
order is held the same way (#3451): a stated value that is not an integer
from 0 to 2147483647 is a 400 naming 'order', so
{"collectionId": "col_2", "order": "9"} refuses the move rather than making
it at the old position - see Ordering.
httpVersion follows the same null-vs-absent rule
as the fields above, but validates more strictly: absent keeps the stored
value; explicit null resets it to the live defaultHttpVersion config value;
a recognized string stores as given; anything else - an unrecognized string, or
a non-string - is a 400 naming the field and the valid values, never silently
coerced. Changing the global defaultHttpVersion afterward does not
retroactively alter a request already saved; only an explicit null on this
request re-seeds it.
preRequestScript, postRequestScript and tests are refused. Issue
1514's cut-over is a clean cut, not a transitional alias: any of these three¶
keys present (even null is accepted as a no-op, but a real value is not) is a
400 naming elements as the replacement. Scripts are elements now -
{"kind": "script.pre" | "script.post", "config": {"script": "..."}}.
elements (issue #1513, run by issue #1514's pipeline) takes the array
rule: absent keeps the stored list; null resets it to []; a present value
must be an array the element registry accepts (see Elements) or
the write is a 400 naming the index, the kind and the field. That includes a
kind's own rules beyond its schema: a JSONPath outside the supported subset, a
pattern RE2 does not compile ('pattern' is not a valid regular expression -
<reason>, likewise 'regex' and 'text', #3043), an assert.status with
neither a non-empty in nor a range, an assert.jsonpath with none of
expected, regex or exists, and one that sets exists beside expected or
regex (#3049), and what the engine would otherwise accept and ignore (#3055): a
control.throughput naming neither or both of percent and everyN, a
timer.think with no ms, gaussian or minMs + maxMs pair, an
assert.contains with an empty text in contains mode, and an extract.*
variable no {{name}} can read (a brace in it, whitespace at an edge, the
data. namespace, $vu or $iteration). The only script
source - GET /requests/:id and every full list response carry it and no longer
carry preRequestScript / postRequestScript at all.
auth.postman, the Postman block an import kept beside the mapped auth
(see db-schema.md), is kept on a write only while mapping it
through the Postman importer still gives the auth being written; otherwise it
is dropped. So a changed credential never leaves the old one behind in the
stored block, whichever client wrote it, and a save that changed nothing keeps
it. POST /requests, POST /collections, PUT /collections/:id and
POST /import/apply apply the same rule.
Headers: If-Match (optional), see
Conditional updates.
Response: The updated request object, with its ETag.
Errors: 404 if the request does not exist; 412 if If-Match no longer
names the stored row; 400 on a malformed If-Match, on a null
collectionId / name / method / url, a collectionId naming a collection
that does not exist, an unrecognized method, a
malformed params / headers entry, a malformed specOperation, a
methodSource that is not "graphql" or null, a mockResponseMode that is
not "first" / "fixed" / "random", a mockExampleId that is not a
non-empty string or null, an auth whose mode is not a
known one (#3464), a malformed protocol setting (see
POST /requests), or an
httpVersion that is not "auto" / "http1.1" / "http2"; 413 naming the
field, its size and the cap, when a serialized params / headers / body /
auth is over the engine's field cap (issue #1485,
see below).
A storage failure answers 507, 503 or 500, never 400 - see
A storage failure is not a 400.
DELETE /requests/:id¶
Delete a request. The delete is soft (issue #988) - the row is stamped
deleted_at and GET /trash lists it until a purge. Its
saved examples stay on the row rather than being removed:
every read of them is by request id and runs the owner check first, so they are
as unreachable as the request is, and a restore gets them back with it. A purge
takes them.
Deleting the request for an operation declines the operation (issue
3031). When the request records an operation (specOperation) and a¶
collection above it binds a document, the same transaction records that
operation under the nearest bound ancestor in spec_declined_operations.
POST /specs/diff then lists the operation as declined
rather than added, and a policy: "safe" sync never
re-creates it, so a sync of the unchanged document cannot bring the request
back. Restoring the request from the trash forgets the record, and so does a
sync that creates the operation on purpose; purging the request, by hand or by
trashRetentionDays, does not - the decision outlives the row it was made on.
Unbinding the collection, or binding it to a document with other bytes, forgets
every record under it. A sync's own deletes record nothing. Moving the request
out of the contract records the same decline (#3446, see
PUT /requests/:id and POST /reorder),
and so does moving a folder above it out with
PUT /collections/:id (#3470);
the move clears the stamp, and a restore forgets only the record of a request
that still records an operation, so deleting and restoring the moved request
later leaves the source's record standing.
Response:
Elements¶
GET /elements/kinds¶
The element registry's catalogue (issue #1513): every kind a request's or
collection's elements array may name, whatever the engine build actually
registers - a kind added in one file (engine/src/core/elements/) appears
here with nothing else changed, per Elements's extensibility
contract. This is what #1516 (app) and #1517 (MCP) render a kind's editor
from, and what docs/engine/elements.md's kind table is checked against.
Response:
[
{
"kind": "inherit.disable",
"version": 1,
"phases": [],
"label": "Disable inherited element",
"description": "Drops one element inherited from an ancestor collection, named by id, out of this request or collection's resolved list.",
"category": "inherit",
"hotPathClass": "declarative",
"collectionOnly": false,
"configSchema": {
"type": "object",
"properties": {
"elementId": {
"type": "string",
"minLength": 1,
"title": "Element to disable",
"description": "The id of an inherited element to drop from this request or collection's resolved list."
}
},
"required": ["elementId"],
"additionalProperties": false
}
}
]
Every property of every kind's configSchema carries a title and a description (issue
1607), plus, where relevant, x-vayu-group: "advanced" (folds the property under a disclosure)¶
or x-vayu-unit ("ms", "%" or "B", a numeric suffix to render) - see
Elements. A property the engine gives a value when its key is
absent also carries default (issue #3045), taken from the constant the kind reads - assert.size
op is "lte", an extract.* scope is "collection", timer.pacing and control.throughput
perUser are true, timer.throughput perUser is false. An absent key means that default; a
client shows it without writing the key.
Phase 0 also registers script.pre and script.post, validate-only like
inherit.disable - so a request or collection the startup fold migrated
(docs/engine/db-schema.md) can be read back and written as-is without its
own elements failing the registry that produced them - plus, in the test
build only, a test.echo kind proving the registration path. collectionOnly
(issue #1499) is true only for script.setup / script.teardown - the app's
Add menu on a request hides a kind marked so, and the registry itself refuses
one on a request's own elements with a 400. See Elements for
the full kind table.
Trash¶
What deleting a collection, a request, an environment, a saved example or a client certificate now does, and how to undo it (issue #988; environments
2970; examples #2971; client certificates #2973). DELETE /collections/:id,¶
DELETE /requests/:id, DELETE /environments/:id,
DELETE /client-certificates/:id and, for an example a person saved
(origin: "user"), DELETE /requests/:id/examples/:exampleId stamp rows
instead of removing them; every other read surface filters stamped rows out, so
the tree, the environment list, a request's examples and the certificate
registry look the same as after a hard delete, and these three endpoints are
the whole of what the stamp buys. An imported example is
not trashed: its delete leaves the tombstone a spec sync reads (see
DELETE /requests/:id/examples/:exampleId).
Two rules decide what a restore of a collection or request puts back:
- Cohort. One delete stamps its whole subtree with one timestamp, and a restore clears exactly the rows carrying the timestamp of the row it was given. So restoring a collection cannot resurrect a request the user had deleted separately beforehand - that request stays in the trash and becomes a root of its own again, since its collection is live.
- Re-parent. A restored collection whose parent is gone, or is itself in the
trash, comes back at the tree root (
parentIdcleared). A request has no such root -collectionIdis required - so restoring one whose collection is in the trash is a409naming the request and its collection by name, and the trash root to restore first by name and id (issue #3449). That root is the listed entry holding the collection: the collection itself, or the ancestor whose delete took it.
An environment needs neither: it owns no rows and hangs under nothing, so its
delete stamps one row, it is always a root, and its restore is unconditional.
A trashed environment is never active. The delete clears isActive in the
same write, so the active slot is free for another environment, and a restore
brings it back inactive: making it active again is a PUT with
isActive: true, the client's choice rather than the trash's.
An example hangs under its request, one level below where a request hangs under
its collection, and follows the request's rule. Its delete stamps its one row.
It is a root only while its request is live: under a trashed request it is part
of what that request's entry stands for, and restoring the request leaves the
example's own earlier delete in the trash as a root again. Restoring an example
whose request is in the trash is a 409 naming the example and its request by
name, and the trash root to restore first by name and id: the request, or the
collection whose delete took it. One whose request is gone is a 409 saying
so, and so is restoring one into a request that already holds the maximum of
100 examples. A stamped example whose request row is gone entirely is listed
nowhere. The delete clears the request's mockExampleId when it named the
example, and the restore does not set it again: choosing it as the fixed mock
answer is the client's write, as making an environment active is.
A client certificate hangs under nothing, like an environment: its delete
stamps its one row and it is always a root, named by its target (host, or
host:port when the entry names a port). A trashed certificate is never
presented. The transport policy every send resolves reads live entries only,
so from the delete on no new design send, stream, collection run or load run offers
it to its host, and the target is free for a new entry. That is also why a
restore can be refused: the registry holds one entry per host and port, so
restoring a certificate while a live entry claims its target is a 409 naming
that entry. The row keeps its passphrase, stored plaintext like every live
entry's, until a purge removes it.
Rows sit in the trash until they are purged: explicitly through
DELETE /trash/:id, or by the startup sweep once they are older than
trashRetentionDays (default 30; 0 keeps them forever).
GET /trash¶
Everything deleted and still restorable, newest first. Roots only - the rows
a user asked to delete, never what their cascade took with them; that is what
collections and requests count, and purgeCollections and purgeRequests
count what a purge would destroy. Every deleted environment and client
certificate is a root; a deleted request is one while its collection is live,
and a deleted example while its request is.
Query Parameters:
- q, limit, offset (optional): one page of the roots whose name holds
q, newest first, in the {data, pagination} envelope instead of
{items, total} - see Paged lists. A cascaded row is not a
root and never matches. A bad limit or offset is a 400
(invalid_limit, invalid_offset).
Response (none of the three):
{
"items": [
{
"id": "col_1234567890",
"kind": "collection",
"name": "Payments API",
"deletedAt": 1787745600000,
"parentId": null,
"collections": 2,
"requests": 14,
"purgeCollections": 3,
"purgeRequests": 16
},
{
"id": "env_1234567890",
"kind": "environment",
"name": "Staging",
"deletedAt": 1787745500000,
"parentId": null,
"collections": 0,
"requests": 0,
"purgeCollections": 0,
"purgeRequests": 0,
"variables": 6
},
{
"id": "exa_1234567890",
"kind": "example",
"name": "200 - created",
"deletedAt": 1787745400000,
"parentId": "req_1234567890",
"parentName": "Create payment",
"collections": 0,
"requests": 0,
"purgeCollections": 0,
"purgeRequests": 0
},
{
"id": "cert_1234567890",
"kind": "clientCertificate",
"name": "api.example.com:8443",
"deletedAt": 1787745300000,
"parentId": null,
"collections": 0,
"requests": 0,
"purgeCollections": 0,
"purgeRequests": 0
}
],
"total": 4
}
kind is "collection", "request", "environment", "example" or
"clientCertificate". A client certificate's name is its target, host or
host:port, which is what q matches. parentId is a collection's parent
(null at the tree root), a request's owning collection, an example's owning
request, or null for an environment and a client certificate.
parentName (issue #3449) is the name of the row parentId names, carried by
a request and an example entry only, so two same-named entries tell apart by
their owner. It is absent on the other three kinds, and on a request or
example whose owner row is gone, which no write path leaves behind.
collections and requests are the cohort: the sub-collections (the root
not counted) and requests this delete took, which is exactly what a restore
puts back. purgeCollections and purgeRequests (issue #3449) are what a
purge destroys: every deleted sub-collection and request
under the root, whichever delete stamped it, stopping at a live collection as
the purge does. They are never below the cohort counts, and exceed them when
an earlier delete inside the subtree - a request, or a folder with its
requests - is waiting under the root, unlisted. All four are 0 for every
kind but a collection. variables is carried by an environment entry only -
the number of variables its stored map holds - and is absent, not 0, on the
other four kinds. An empty trash is {"items": [], "total": 0}, never a
404.
POST /trash/:id/restore¶
Put a deleted collection, request, environment, example or client certificate
back, with everything the same delete took. Takes no body. An environment comes
back exactly as it was deleted except that it is inactive (see Trash),
and its answer carries variables like its list entry. An example comes back
exactly as it was deleted, order included, but its request's
mockExampleId, cleared by the delete, stays null (issue #3422); a client
certificate comes back exactly as it was, passphrase included. A restored request, alone or with its collection, takes
back the operation its delete declined (issue #3031), so the next sync sees it
claimed again.
Response: the entry that was restored, plus what happened to it:
{
"id": "col_1234567890",
"kind": "collection",
"name": "Payments API",
"deletedAt": 1787745600000,
"parentId": null,
"collections": 2,
"requests": 14,
"purgeCollections": 3,
"purgeRequests": 16,
"restored": true,
"reparentedToRoot": false
}
Errors:
| Status | When |
|---|---|
404 |
Nothing in the trash carries that id - a live row, or one already purged |
409 |
A request whose collection is itself deleted or gone; the message names the request and its collection, and the trash root to restore first by name and id |
409 |
An example whose request is itself deleted or gone; the message names the example and its request, and the trash root to restore first by name and id |
409 |
An example whose request already holds the maximum of 100 examples; delete one first |
409 |
A client certificate whose host and port a live entry now claims; the message names that entry, to delete first |
DELETE /trash/:id¶
Destroy a deleted collection, request, environment, example or client certificate for good, with its whole subtree - requests, and the examples they own, trashed ones included; an environment, an example or a client certificate is its one row (a certificate's passphrase goes with it), and an environment takes its cookie jar with it. This is the hard cascade soft delete replaced, asked for deliberately; there is no undo for it.
Unlike a restore, a purge is not limited to the cohort: a row an earlier delete
left inside the subtree goes too, because a request under a removed collection
is reachable by no read and restorable by nothing. It takes deleted rows only
(issue #1883): a live collection under the purged one, which no trash entry ever
listed, is moved to the tree root (parentId cleared) with everything under it
left as it was.
A purged request's declined operation (issue #3031) stays declined: purging is emptying the trash, not changing one's mind. A purged bound collection takes the declined operations recorded under it, which nothing could read any more.
Response: the entry that was purged, with "purged": true. Its
purgeCollections / purgeRequests count what this purge destroyed, an
earlier delete's rows under the root included; its collections /
requests are still the deleted row's own cohort. A 404 if the trash does
not hold that id - which is also what stops a mistyped id from destroying a
live collection.
Request examples¶
Saved example responses for a request: what an importer found next to it
(Postman's item.response[], an OpenAPI operation's responses), and the
responses a mock server will serve. Nested under the request because an example
is owned by exactly one - the owner is checked before the example on every path,
so an example reached through the wrong request is a 404, not a cross-request
write.
Ordering is part of the contract, not a display preference: the list is
returned by order, then createdAt, then id, and a mock server answers with
the first example of the matched request. A create that states no order
appends after the request's current examples; a bulk import numbers them by
payload position, because every row it writes shares one createdAt and would
otherwise come back shuffled by the id tiebreak.
Caps. A body over 1 MiB is a 400 rather than a truncation - an
example served as if it were whole when it is not is worse than a refused write
- and a request holds at most 100 examples. Only live ones count: a
tombstoned or trashed example does not, which is why restoring one into a full
request is refused (see Trash).
A zero byte in a body ("ab\u0000cd") is preserved: it is stored, listed and served by a
mock server whole, never cut at the zero.
origin says who wrote the row (issue #588): "import" for everything an
importer or a spec sync produced, "user" for one a person saved from a live
response. It defaults to "import", which is honest for every row written
before the column existed, and an unrecognised value is a 400 rather than a
silent fall back - the OpenAPI spec sync (#627) may replace "import" rows
wholesale and must never touch a "user" one, so an absorbed typo would cost a
user their saved example. An OpenAPI export carries it on every example in
x-vayu-request.examples so a re-import keeps it (#2430).
bodyTruncated says the body stops short (issue #659). A mock server serves
a stored example verbatim, with nothing in the response to say anything is
missing, so an example saved from a capped trace body (maxTraceBodyBytes) is
served as though it were a whole response. Only the client that captured it can
know, so the flag is stored rather than inferred - a short body is a legitimate
body. It defaults to false, which is honest for every row written before the
column existed: import copies a whole documented body, and the app's
save-as-example is the only writer that ever had a partial one. The app disclosed
this in the example's name until the column landed, which a rename at save time
erased.
GET /requests/:id/examples¶
Response: an array of example objects, oldest first:
[
{
"id": "exa_1234567890",
"requestId": "req_1234567890",
"name": "200 - A user",
"status": 200,
"headers": [{"key": "Content-Type", "value": "application/json", "enabled": true}],
"body": "{\"id\":1}",
"contentType": "application/json",
"order": 0,
"origin": "import",
"bodyTruncated": false,
"createdAt": 1730000000000,
"updatedAt": 1730000000000
}
]
An empty array and a missing request are different answers: 404 (message
Request not found) means the request does not exist, [] means it has no
examples yet.
POST /requests/:id/examples¶
Create one example. Create only, and the engine owns the id - see Resource writes.
Request:
{
"name": "200 - A user", // Required, no default (null is a 400)
"status": 200, // Optional, must be 200-599. Default 200
"headers": [], // Optional, array of {key, value, enabled}
"body": "", // Optional. Default ""
"contentType": "", // Optional. Default ""
"order": 0, // Optional, appended after the request's examples if omitted
"origin": "import", // Optional, "import" | "user". Default "import"
"bodyTruncated": false, // Optional. Default false - true when `body` is
// only the first slice of the captured response
"postmanResponse": null, // Optional. The Postman saved response an import
// took this from, as JSON text; null = none
"savedFrom": null // Optional, create only. What a save in the app
// says produced the response (see below); null = none
}
savedFrom is what the app's save-as-example sends from a live response
(#1763): the request as written when it was sent ({{variables}}
unresolved) and the server's own reason phrase. The engine builds the
example's Postman saved response from it with the exporter's own mapping, so
POST /export/postman writes that request as originalRequest even after the
request is edited.
"savedFrom": {
"request": { // Required; the request columns' own shapes
"method": "POST", // Required, an HTTP method (any case)
"url": "{{baseUrl}}/users/:id", // Required string, as written
"params": [], // Optional array, default []; path rows too
"headers": [], // Optional array, default []
"body": {"mode": "none"} // Optional object, default {"mode":"none"}
},
"statusText": "Totally Fine", // Required string; "" = the status table's
"responseTimeMs": 123, // Optional number, 0 or more; absent = null
"receivedAt": 1767225600000 // Optional epoch ms, 0 or more: when the
// response came in; absent = the save's clock
}
The stored copy holds name (null), originalRequest (method, headers,
body and url as the export writes a request's, with no auth), status
(statusText), code, _postman_previewlanguage, header (the example's
own rows), cookie (one entry per cookie the enabled Set-Cookie rows set,
in Postman's member order: expires, hostOnly, httpOnly, domain, path,
secure, session, value, key; expires is JavaScript's date text in
UTC, from Max-Age counted from receivedAt (the engine's clock at the save
when absent) when there is one, else Expires, and "Invalid Date" with
session: true for a cookie with neither; the attributes are read as RFC 6265
and Postman's cookie store read them: an empty Domain is ignored, a leading
. dropped, a Path not starting with / is /, and the space around = is
not part of a name or value),
responseTime (whole milliseconds) and body (null). When it
would be over the 1 MiB cap (a large request body) the example is still
created, without it, and a warning is logged; the export then regenerates
those members. PUT ignores a savedFrom key.
postmanResponse is what the Postman importer sends (schema version 2): the
item.response[] entry as JSON text in the source's member order, name
and body replaced by null placeholders. A string rather than an object so the
order survives a parse into sorted JSON on the way here; it must parse as a JSON
object, and it is capped at 1 MiB. POST /export/postman is its reader, and no
read route returns it.
headers is an array of KeyValueEntry, the same shape a request's headers
use - not a JSON object. A stored example is re-served rather than only
displayed, so repeated names (Set-Cookie) and the author's ordering both have
to survive.
Response: the created example object.
Errors: 404 if the request does not exist. 400 if the body carries an
id, if name is missing or null, on a status outside 200-599 (rejected
rather than clamped - a stored 700 would be re-served as a status line nobody
can send, and a 1xx is an interim response a mock cannot serve as its final
answer), on a malformed headers entry, on an origin that is neither
"import" nor "user", on a body over the cap, or on a postmanResponse that
is not a string holding a JSON object or is over its cap. 400 naming the field
on a savedFrom that is not an object, whose request is not an object, whose
method is missing or not an HTTP method, whose url is not a string, whose
params or headers is not an array, whose body is not an object, whose
statusText is not a string, whose responseTimeMs or receivedAt is
negative or not a number, and on a savedFrom beside a non-null postmanResponse (two writers of
one column). 409 when the request
already holds the maximum number of examples.
A storage failure answers 507, 503 or 500, never 400 - see
A storage failure is not a 400.
PUT /requests/:id/examples/:exampleId¶
Update one example. Update only - a 404 when the example does not exist,
and the same 404 when it exists under a different request. Merge-patch body:
absent keeps, null resets to the field's default (name has none, so null
is a 400). A status outside 200-599 is a 400 as on create; only a body
that names status is judged, so an example stored with a 1xx before create
began refusing them can still be renamed. postmanResponse accepts only
null, which clears it; any other value is a 400 - it records what a file
said, and the export already regenerates each part of it an edit to status or
headers makes stale.
Headers: If-Match (optional), see
Conditional updates.
Response: the updated example object, with its ETag.
Errors: 404 as above; 412 if If-Match no longer names the stored row;
400 on a malformed If-Match or a rejected field.
A storage failure answers 507, 503 or 500, never 400 - see
A storage failure is not a 400.
DELETE /requests/:id/examples/:exampleId¶
Deleting an imported example is a decision that lasts (issue #722). A spec
sync rewrites the origin: "import" examples of every request it applies a
change to, so a removed row used to come back on the next sync of any field -
even a rename. The engine now keeps the row as a tombstone instead: the
example is gone from every read (the list, a mock server, an export, and a GET
or PUT on its id, all 404), and a later sync leaves that response status
alone rather than writing the document's example for it back. Re-importing the
document is a fresh import and does bring it back, which is the only way it
returns.
Deleting an example a person saved moves it to the trash (#2971).
An origin: "user" example is stamped deleted_at rather than removed:
nothing re-creates one, so the row is the only copy of the response. It is gone
from the same reads a tombstone is, a second DELETE is a 404, it no longer
counts against the 100-example cap, and GET /trash lists it
(kind example, parentId its request) while its request is live.
POST /trash/:id/restore brings it back as it was;
DELETE /trash/:id, or the startup sweep after
trashRetentionDays, destroys it.
Either way, a request that named the example as its fixed mock answer stops
naming it (issue #3422). When the request's mockExampleId is this example's
id, the same write clears it to null, advances the request's updatedAt (so
a PUT /requests/:id sent with the old If-Match is a 412) and publishes a
request update on GET /changes after the example's
delete. mockResponseMode is not
touched: a "fixed" request with no target answers with its first example. A
mockExampleId naming any other example is left alone, and a restore from the
trash does not set it again.
The response is the same either way, because from the caller's side so is the outcome:
Response:
Specs¶
OpenAPI documents, stored once and bound to collections by
collections.openapi (issue #637). A spec is not owned by a
collection: several may bind the same document, and unbinding one must leave it
there for the others - so it is a top-level resource with no cascade reaching it,
and the rule that keeps that safe is the delete refusal below. What it is not
is immortal: see the reclamation rule further down.
The document is stored verbatim and its hash is computed engine-side on
every write, never taken from the caller. A scenario run of a bound collection
stamps specId + specHash into its snapshot and report, and that stamp only
means anything because both sides of a later comparison were computed by the same
code on the same bytes.
There is deliberately no PUT /specs/:id: a document that changed is a
different document, and rewriting one in place would invalidate the hash every
run of every bound collection was stamped with. A re-fetch stores a new document
and moves the binding.
A document nothing can reach is reclaimed (issue #718). Having no owner is
what let these rows accumulate with no way to die - every sync mints one and
moves the binding off the last, and DELETE /specs/:id needs an id no route
hands out for an unbound document. So the engine sweeps on one rule:
A document lives while a collection binds it, or while a retained run names it in its snapshot under
scenario.openapi.specId.
Run-referenced documents live exactly as long as the runs do, so a report's
coverage never describes a contract whose source is gone. The sweep runs as part
of ordinary housekeeping - at startup, after each run's retention pass, after a
POST /specs/sync, and after a DELETE /collections/:id - and spares any
document written in the last 10 minutes, because storing a document is the
first of the three writes that bind one and a caller may not have sent the
PUT /collections/:id yet. A client that stores a document it does not intend to
bind should therefore expect it to go: GET /specs/:id will answer 404 once it
is unreachable by that rule. Nothing here changes what DELETE /specs/:id
refuses, and no cascade was added - a bound document is untouched.
POST /specs¶
Store one OpenAPI document. Create only, and the engine owns the id - see Resource writes.
Request:
{
"content": "{\"openapi\":\"3.1.0\", ...}", // Required, non-empty, at most maxSpecDocumentBytes
"sourceUrl": "https://api.example.com/openapi.json" // Optional; null when pasted or uploaded
}
Response:
{
"id": "spec_3f2b1c9a-...",
"content": "{\"openapi\":\"3.1.0\", ...}",
"sourceUrl": "https://api.example.com/openapi.json",
"fetchedAt": 1730000000000,
"hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"operations": [
{"operationId": "listPets", "method": "GET", "path": "/pets", "responses": ["200", "default"]}
]
}
operations is derived by the engine, never sent (issue #853). It is a fact
about the bytes being stored, like hash, so the engine reads them: content is
parsed as JSON and then, failing that, as YAML, and the operation index comes off
that parse. Sending an operations field is a 400.
Each row carries a method and the templated path as the document keys it,
an operationId when the document declares one, and responses - the status
patterns the document declares ("200", "4XX", "default"), verbatim and in
document order. A document declaring more than 2000 operations is refused
with the count and the cap, because a run holds the index in memory for its life.
What the reader does with a document, stated because the answers are visible in the index:
- Document order is kept, for
pathsand for each operation'sresponses. - Both formats:
openapi: 3.xandswagger: 2.0(quoted or not). Anything else declares nothing - a stored file that is not a contract stores fine and reports no coverage. - A path item that is a
$refis followed one hop, in-document; one that resolves to nothing drops that path rather than failing the write. - The seven methods Vayu executes are indexed,
traceis not. - A repeated
operationIdis kept on its first declaration only (issue #715); the later operation is indexed by method and path alone. - Anchors, aliases and merge keys (
<<) are expanded as js-yaml expands them; an alias naming no anchor, a duplicate mapping key, and a document that expands to far more nodes than its own size are each a400naming the problem.
A document that declares no operation stores "no index", which is not the same as
an empty contract: GET /specs/:id reads it back as null rather than [], and
a run of a collection bound to it reports no coverage block at all. POST
/import/apply's spec section and POST /specs/sync derive both indexes through
the same helper, so a document cannot acquire or lose one depending on which
route stored it.
responseSchemas is the second index the engine derives from the same read
(issues #628 and #860) - what the document declares each response looks like.
Like operations, it is not a field of the body; sending one is a 400:
{
"refRoots": {"components": {"schemas": {"Pet": {"type": "object"}}}},
"operations": [
{
"operationId": "getPet",
"method": "GET",
"path": "/pets/{petId}",
"responses": [
{"status": "200", "contentType": "application/json",
"schema": {"$ref": "#/components/schemas/Pet"}}
]
}
]
}
A response schema that refers to itself without describing any value is a
400 (#3018): Response schema of GET /pets (200) refers to itself without
describing any value (#/components/schemas/A -> #/components/schemas/A). The
loop runs only through $ref, allOf, anyOf, oneOf, not, if/then/else
or dependencies, so it never reaches a value and cannot be validated. A
recursive schema that steps into a property or an item (a tree node) is fine.
Schemas are JSON Schema, not OpenAPI's dialect: the engine translates
nullable into a union with null, draft-04's boolean exclusiveMinimum into
draft-07's numeric one, and drops the OpenAPI-only keywords that constrain no
body (discriminator, xml, externalDocs, example) - a nullable passed
through untouched would report a null the document permits as a type failure,
which is a wrong verdict rather than a missing one. Each schema keeps its
$refs and refRoots carries the subtrees they point into once
(components.schemas, definitions, x-vayu-bundled), so a shared schema is
stored once and a recursive one is a pointer rather than an infinite expansion.
A response that is itself a $ref is read through, one hop, in either
dialect (#/components/responses/x in 3.x, #/responses/X in 2.0) - the shape
GitHub's spec uses for nearly every response. status is the pattern verbatim
("200", "4XX", "default"), contentType is a media type (3.x keeps every
one the response declares; 2.0 pairs each response with the operation's
produces, falling back to the document's, then to application/json), and a
schema may be true or false as well as an object. The serialized index is
held to the same maxSpecDocumentBytes cap as the document, and one over it is a
400 naming the count and the cap. A status that declares no schema is a
status-only row ({"status": "204", "contentType": ""}, no schema), so a
response under it reports checked: false instead of being judged by default.
An x- extension key under responses is not a status and is indexed in
neither list (#3084).
A document where no operation declares a status stores "no index", read back as
null, and every response of it reports checked: false with the reason
no_index.
Both indexes come off one read of the document, which is what makes them
agree: a status the schema index carries is a status the operation index lists
for the same operation, and the identity in each is the same identity - the
repeated-operationId rule included.
sourceUrl is null rather than "" when the document did not come from a URL,
so a client can offer a re-fetch for exactly the documents that have somewhere to
re-fetch from.
Errors: 400 if the body carries id, hash, fetchedAt, operations or
responseSchemas (all engine-computed), if content is missing, null or empty, if sourceUrl is
present and not a string or null, or if the document is larger than the live
maxSpecDocumentBytes config entry - default 10 MiB, aligned
with the engine's JSON field cap. The size rejection names the byte count, the
cap and the setting, and is checked on POST /import/apply too, through the same
helper; the document is never stored truncated. A content the engine cannot
read as JSON or YAML is a 400 naming the line - storing it would leave a row
that coverage, a sync and an export can each do nothing with, and none of those
is a good place to find out.
A storage failure answers 507, 503 or 500, never 400 - see
A storage failure is not a 400.
GET /specs/:id¶
Response: the whole stored document, content included - rendering and
validating it is what every reader wants it for. 404 (message Spec not found)
when it does not exist.
Read it for the text: an export, a re-fetch comparison, a $ref resolution.
A client that only needs to describe the document should read the metadata route
below instead - content here is up to maxSpecDocumentBytes (12 MB for
Stripe's published spec), and it is sent in full on every read.
GET /specs/:id/meta¶
Everything about a stored document except the document (issue #712).
Response:
{
"id": "spec_3f2b1c9a-...",
"sourceUrl": "https://api.example.com/openapi.json",
"fetchedAt": 1730000000000,
"hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"contentBytes": 12058329
}
Every field carries the same value GET /specs/:id would give it - the two are
one row seen two ways - and 404 is the same body, so a client that falls back
from one to the other does not need two shapes of "not found".
content, operations and responseSchemas are absent, not empty. All
three are the fields that make a document big (both indexes are extracted from
it and grow with it), and an empty one would be indistinguishable from a
document that genuinely has none - the distinction operations: null exists to
draw. A reader that needs any of them reads the full route.
contentBytes is the document's size as the engine counts it - the same measure
maxSpecDocumentBytes refuses a write by, so a size reported here and the limit
it was stored under are in one unit.
This route exists because binding metadata lives on the document: the app's Spec tab paints a source and a fetch date, and getting them used to cost a transfer of the whole spec on every first open of the tab.
DELETE /specs/:id¶
Delete a stored document.
Response:
Errors: 404 when it does not exist. 409 while any collection still binds
it, a collection in the Trash included, with a message naming the first binder
(and a count of the rest) so the caller knows what to unbind without a second
round trip:
{
"error": {
"code": "conflict",
"message": "Spec 'spec_3f2b...' is bound by collection 'Pets API' (col_9a1f...); unbind it before deleting the document"
}
}
A binder in the Trash is named as such (#3446), because restoring it brings its binding back and a document deleted under it would come back named by a collection whose document is gone:
{
"error": {
"code": "conflict",
"message": "Spec 'spec_3f2b...' is bound by collection 'Pets API' (col_9a1f...), which is in the Trash; restore it and unbind it, or purge it, before deleting the document"
}
}
The refusal is deliberate rather than a cascade to unbound: the caller asked to
delete a document, not to edit collections it never mentioned. Unbind with
PUT /collections/:id and {"openapi": null}, then delete. Purging a trashed
binder runs the orphan sweep, which reclaims the document itself once nothing
else binds it.
POST /specs/match¶
Pair the requests in a collection's subtree with the operations a document declares - what binding a collection that already exists needs, and what an import does not (an import creates the requests, so it stamps each one's identity as it builds it).
Reads only. Nothing is stored, stamped or created, so a caller may ask about
a document it has not decided to bind - which is exactly what the app's Spec tab
does, showing the counts before the user commits. The write is
POST /specs/bind, which matches again over the same walk and
the same rule rather than being handed this answer: between a preview and a
commit a request may have moved, so what the two share is the rule, not a result
carried between them.
Request:
{
"collectionId": "col_9a1f...",
"operations": [
{ "operationId": "listPets", "method": "GET", "path": "/pets" },
{ "method": "GET", "path": "/pets/{petId}" }
],
"basePaths": ["/v1"]
}
operations are the same identity rows the engine derives into a document's
operations index, validated by the same rule - so a set the store would refuse
cannot be matched against here first. They are sent here (unlike on
POST /specs, which reads them off the document) because this route matches
against a document that has not been stored yet, which is the point of a bind
preview. Get them from POST /specs/describe rather
than by reading the document yourself (issue #869): that route is the same reader
POST /specs/bind derives its stamps from, so a preview and the write it
previews cannot pair the requests differently. responses may ride along and is
ignored. basePaths is optional: the path parts of the document's server URLs,
which POST /specs/describe answers beside the operations (issue #3030). A
non-array, or an entry that is not a string, is a 400; an entry that does not
start with /, or is the root, names nothing to strip and is ignored.
The requests are not sent. The engine gathers the subtree of
collectionId itself, because an OpenAPI import binds the root and files every
request under one sub-collection per tag: a caller sending "the collection's
requests" would be matching against a set that excludes almost all of them. The
walk stops at a sub-collection bound to a different document (issue #3034),
taking its descendants with it: a folder that is another contract's own keeps
its requests out of this pairing, exactly as POST /specs/bind keeps them out
of its stamping. A sub-collection bound to the same document stays in, and an
unbound collectionId stops at every bound sub-collection.
Response:
{
"matched": [
{
"requestId": "req_4c8e...",
"operation": { "operationId": "listPets", "method": "GET", "path": "/pets" }
}
],
"unmatchedRequests": ["req_7b21..."],
"unmatchedOperations": [{ "method": "GET", "path": "/pets/{petId}" }]
}
operationId is absent rather than "" for an operation that declares none,
the same way a stored spec_operation omits it.
How it matches. Both sides are reduced to a path shape: the origin dropped
({{baseUrl}}, https://api.example.com and a schemeless host alike), the query
and fragment dropped, and every placeholder - Vayu's {{petId}}, a request's
Postman-style :petId path variable (issue #1764) and the document's {petId} -
flattened to {}. Flattening the name too is deliberate:
a document that renames its path parameter describes the same endpoint, and a
match that turned on the parameter's spelling would report a rename as removed
and added. A second pass then offers each remaining request to the templates it
could be an instance of, because a hand-built collection writes the id in
(/pets/42) - a literal path in the document wins first, which is OpenAPI's own
precedence. A segment mixing literal text with a placeholder ({id}.json,
{name}:cancel, meta-{ver}, issue #3085) is filled the same way: the text
around the placeholders must appear in order and each placeholder takes at
least one character, never a /. A third pass reads basePaths (issue #3030):
a request written as a literal URL carries the server's base path
(https://h/v1/pets) where the
document writes /pets, so whatever the first two passes left open is compared
again, both ways, with each base path taken off the front of the request's path.
A base path is taken off whole segments only (/v1 is not a prefix of
/v10/pets), a templated one (/{version}) stands for any one segment (a
segment mixing text with a placeholder, /api-{version}, fills as above), and a
request that is exactly the base path is the root operation /. The first two
passes win, so a document declaring /v1/pets in full claims that request
before any base path is stripped. Ambiguity is refused in both directions,
in every pass: two requests reducing to one shape, or one request that could be
two operations - under two base paths included - leaves all of them unmatched.
A wrong identity is worse than none, because POST /specs/sync applies changes
by it.
Errors: 400 for a missing or empty collectionId, a missing operations,
an operation row the store would refuse, or a basePaths that is not an array
of strings. 404 when the collection does not
exist - not an empty match, since "this document matches none of your requests"
and "you named a collection that is not there" are different answers.
POST /specs/describe¶
Say what a document is, without storing it: the dialect that claimed it, what
it calls itself, every operation it declares and the base paths its servers
name. The read behind a bind
preview - the app's Spec tab paints its card from this and hands the identities
straight to POST /specs/match.
Reads only. Nothing is stored, which is why the document rides in the body:
a caller asks about a file the user has not decided to bind, and a route that
stored one to describe it would leave a row behind for every file merely looked
at. Describing a document that is stored is
GET /specs/:id/meta.
Request:
Response:
{
"format": "OpenAPI 3.1",
"title": "Pets API",
"operations": [
{ "operationId": "listPets", "method": "GET", "path": "/pets" },
{ "method": "GET", "path": "/pets/{petId}" }
],
"basePaths": ["/v1"]
}
format is "OpenAPI 3.1" (an openapi starting 3.1), "OpenAPI 3.0" (any
other 3.) or "OpenAPI 2.0 (Swagger)". title is the
document's info.title and "" when it states none - never a substitute name,
because the caller asked what the document calls itself. operations are in
document order, in the shape a request's spec_operation records, operationId
absent rather than "" for an operation that declares none - the same rows
POST /specs/match takes.
basePaths (issue #3030) is always present, [] when the document states
none, and is what POST /specs/match takes beside the operations. For 3.x it
is the path of every servers[].url, not only the servers[0] an import
turns into {{baseUrl}}, because a collection may have been written against any
of them: each {name} with a variables default is substituted first (the
importer's rule), then the path after the authority is taken
(https://{host}/v1 -> /v1), or the whole URL when it is already a path. A
server with no path, or one relative to the document (v1), names none. For
2.0 it is basePath. Trailing slashes are dropped, and the root and repeats are
left out.
This is the reader every spec write uses (issue #853), which is the point of the
route: the identities answered here are the identities
POST /specs/bind will derive from the same bytes. Before
issue #869 the app read the picked document itself, so a document the two sides
read differently previewed one pairing and committed another.
Errors: 400 for a missing or empty content, bytes over
maxSpecDocumentBytes (the same cap a store applies, so a preview cannot succeed
where the bind will fail), bytes that cannot be read as JSON or YAML, a document
declaring more than 2000 operations, and a readable file that is not an
OpenAPI document - the last named as what is missing rather than answered as a
contract declaring nothing.
POST /specs/diff¶
What a re-fetched document would change about the collection bound to it - the read half of a sync (issue #654's comparison, moved engine-side by #854). The app's Sync section is this call; an agent asking "has this contract drifted, and where" is the same one.
Reads only. No document is stored, no binding moved, no request stamped, so
a caller may ask about a document it has not decided to apply. Applying is
POST /specs/sync, which re-reads everything rather than
being handed this answer - the same split POST /specs/match and
POST /specs/bind follow.
Request:
Neither the requests nor the bound document are sent. The engine walks the
subtree of collectionId itself (an import files its requests under one
sub-collection per tag, and the walk stops at a sub-collection bound to a
different document, issue #3034) and reads the bound document from the
collection's own binding: the three-way rule below is only worth anything if the "previous" side
is the bytes actually stored, and a caller that could supply them could turn its
own edits into the document's - by accident, with a stale copy.
Response:
{
"identical": false,
"added": [
{
"operation": { "operationId": "listOwners", "method": "GET", "path": "/owners" },
"folder": "owners",
"safe": true,
"draft": {
"name": "List owners",
"description": "",
"method": "GET",
"url": "{{baseUrl}}/owners",
"params": [],
"headers": [],
"body": { "mode": "none" },
"examples": []
}
}
],
"declined": [
{
"operation": { "operationId": "getPet", "method": "GET", "path": "/pets/{petId}" },
"folder": "pets",
"safe": false,
"draft": { "name": "Get a pet", "...": "as in added" }
}
],
"removed": [
{
"requestId": "req_7b21...",
"name": "Delete a pet",
"operation": { "operationId": "deletePet", "method": "DELETE", "path": "/pets/{petId}" },
"safe": false
}
],
"changed": [
{
"requestId": "req_4c8e...",
"name": "List pets",
"boundOperation": { "operationId": "listPets", "method": "GET", "path": "/pets" },
"operation": { "operationId": "listPets", "method": "GET", "path": "/pets" },
"matchedBy": "operationId",
"renamed": false,
"previousUnknown": false,
"safe": true,
"safeFields": ["name"],
"fields": [
{
"field": "name",
"current": "List pets",
"next": "List all the pets",
"userTouched": false
}
],
"draft": { "name": "List all the pets", "...": "as above" }
}
],
"unchanged": 12,
"unmapped": 1
}
identical is decided on the stored bytes - the ones spec_documents.hash
is over - rather than on a hash the caller computed, and is the "up to date"
answer. The buckets are still reported when it is true, empty.
draft is the request an import of the new document would build: the values
behind every next (which is truncated for display), plus the operation's
documented responses as examples, so a POST /specs/sync payload is built by
choosing which of these fields to send rather than by re-reading the document.
The examples here are reported rather than returned to the engine: since issue
869 a sync says whether to refresh a request's imported examples and the rows¶
come off the document it stores, so this is what an apply would write, shown.
unmapped counts requests carrying no operation at all - not part of the
comparison, but stated, because a sync that silently ignores half a collection is
one nobody can read.
declined is an operation nobody claims because a person deleted its
request (issue #3031). Its entries are shaped like added ones, because
ticking one is the same create, and an operation is in one bucket or the other,
never both. The record a delete left (see
DELETE /requests/:id) is followed into the new document
by the rule a request's own identity is, below, so an operation the document
renamed is still the declined one. A live request claiming the operation - one
restored from the trash, or created again by hand - outranks the record, and
the operation is in neither bucket.
safe is what an apply with no ticks would do to that entry (issue #871),
and safeFields is which of a changed request's fields it would write - empty
for a pure rename, which is a real selection rather than an absence. It is
core::safe_spec_apply: every operation the document adds, every field it
moved that nobody here had edited, no deletions, nothing a person declined, and
a request whose bound document could not be read left alone whole. Reported rather than left to the
caller because the rules are the ones whose silent failure costs somebody their
work, and because the same function decides what
POST /specs/sync's policy applies - so the app's
pre-ticked boxes and a caller that ticks nothing are one answer rather than two
that agree today. safe on a removal and on a declined operation is always
false and is carried anyway, so that a reader marking the bucket reads the
rule instead of writing it.
How it compares. An operation is followed by its operationId first and by
method + path shape second (the same flattening POST /specs/match binds with),
so a path moved under a stable id and an id moved under a stable path both stay
one operation, while both moving at once is disclosed as a removal plus an
addition rather than guessed at. An id two requests claim identifies neither
and is skipped; an id whose entry contradicts the endpoint the request records
loses to an exact match on that endpoint. renamed says the identity itself
moved, so an apply records the new one.
userTouched is three-way: the field is flagged when what the request holds
is neither what the new document produces nor what the bound one did - the
only evidence that a person put it there, and the flag an apply may not overwrite
silently. previousUnknown says the bound document does not declare this
operation, so no such claim can be made about it at all, and every userTouched
on that request is false. A query typed into the URL is a Params change too:
the write that stored the URL derived the query rows from it (see
POST /requests, issue #3551), so params is flagged beside
url.
Response examples are deliberately not compared. The rule that governs them
(origin="import" is replaced, origin="user" survives) only means anything at
apply time, so they ride on draft rather than appearing as a difference nothing
acts on.
Errors: 400 for a missing or empty collectionId, a missing or empty
spec.content, a document larger than maxSpecDocumentBytes, a document that
will not read as JSON or YAML (the message names where it broke), or a collection
that binds nothing - there is nothing to compare against, and binding is
POST /specs/bind. 404 when the collection does not exist.
409 when its binding names a document the store no longer holds, which is a
broken binding rather than a bad request.
POST /specs/bind¶
Bind a collection to an OpenAPI document, in one transaction: the document is
stored, the collection's binding moves to it, and every request in the
collection's subtree is stamped with the operation it matched or has its stamp
cleared. Nothing is created or deleted - that is what a sync is for. It is the
one way to bind or rebind an existing collection: PUT /collections/:id with
any openapi but null or {} is a 400 naming this route (issue #3348).
The caller sends a document, never a pairing. The engine reads the bytes it
is about to store, derives the operations index from them, and matches the
subtree with core::match_operations - the same rule POST /specs/match
previews with, over the same subtree walk, under the base paths the same read
of the document names (the basePaths POST /specs/describe answers, issue
3030). A pairing worked out by the caller¶
would be a second opinion about what the document declares, and an agent over MCP has bytes and no OpenAPI reader at all.
Request:
{
"collectionId": "col_9a1f...",
"spec": {
"content": "openapi: 3.0.0\n...",
"sourceUrl": "https://api.example.com/openapi.yaml"
}
}
spec.content is the document verbatim, JSON or YAML, capped by
maxSpecDocumentBytes. sourceUrl is optional and null or absent means the
document did not come from a URL. id, hash, fetchedAt, operations and
responseSchemas are engine-computed and a 400 if sent, the same rule
POST /specs applies.
Response:
{
"specId": "spec_2b74...",
"specHash": "8f3c...",
"syncedAt": 1755000100000,
"stamped": 12,
"cleared": 2,
"unmatchedRequests": ["req_7b21..."],
"unmatchedOperations": [{ "method": "GET", "path": "/pets/{petId}" }]
}
unmatchedRequests and unmatchedOperations carry the same shapes
POST /specs/match answers with, so a caller reads one shape for the preview and
the commit.
Stamping goes both ways (issue #718). After a bind, a request's
spec_operation is the operation it matched in the bound document, or nothing:
cleared counts the requests whose identity was removed because this document
does not account for it. That half is not a list the caller states - it is the
other side of the same walk - because a bind that wrote only the matches left
every non-matcher carrying identity from the previous document, and coverage
resolves a stamp by operationId first, so such a stamp claims whichever
operation of the new document shares the id rather than going unread.
Nothing outside the subtree is touched, the rule POST /specs/sync follows:
a request under another collection keeps its own stamp even when it would have
matched. That includes a sub-collection bound to a different document and
everything beneath it (issue #3034): its requests carry that document's
operation identity, so neither a match nor a clear is applied to them. A
sub-collection bound to the same document is in the subtree.
A bind to other bytes forgets the declined operations (issue #3031). The
operations deletes declined under the collection (see
DELETE /requests/:id) were decisions about the document
it was bound to, so a bind whose document hashes differently from the bound one
forgets them in the same transaction; a bind to the same bytes keeps them.
Errors: 400 for a malformed body, an engine-owned field, a document over
the cap, or one that cannot be read as JSON or YAML - and in that last case
nothing is written, so the collection stays bound to whatever it was bound to.
404 when the collection does not exist. 409 when a row moved under the write.
Unbinding is not here: it is PUT /collections/:id with "openapi": null (or
{}), which writes one row, leaves every stamp in place - so unbind-then-rebind
of the same document is lossless - and has no document to read. It does forget the declined
operations, in the same transaction, as a bind to other bytes does.
POST /specs/export¶
A collection back out as an OpenAPI document - its own bound document updated,
or a skeleton describing its requests when it binds none. Which of the two runs
is a fact about the collection rather than a parameter; how much a bound export
writes is the caller's choice (mode, below).
Reads only. Nothing is stored and the collection is left exactly as it is; a POST because the answer is a document rather than a resource, and because the body carries the format.
Request:
{
"collectionId": "col_9a1f...", // Required
"format": "json", // Optional - "json" (default) or "yaml"
"mode": "contract" // Optional - "contract" (default) or "full"
}
Neither the requests nor the document are sent. The engine reads the whole
subtree of collectionId (an OpenAPI import binds the root and files every
request under one sub-collection per tag), each request's stored examples, and
the bound document itself - stopping at any collection bound to a different
document. That boundary is not a filter: the refused collection takes its own
descendants with it, because its requests carry another document's operation
stamps and operationIds are names generators hand out in every document
(listUsers, GET /users), so letting them through would have them claim these
operations and rewrite them. A descendant bound to the same document is part
of the export, because its requests describe the very operations being patched.
Response:
{
"text": "{\n \"openapi\": \"3.0.3\",\n ...",
"fileName": "petstore.openapi.json",
"notes": {
"direction": "document", // or "skeleton"
"dialect": "OpenAPI 3.0.3",
"requestsExported": 12,
"requestsWithoutOperation": 1,
"operationsNotInDocument": 0,
"operationsRemoved": 2,
"requestsWithoutPath": 0,
"duplicateOperations": 0,
"examplesWritten": 4,
"examplesWithoutMediaType": 1,
"examplesTruncated": 0,
"examplesAlreadyDeclared": 3,
"examplesSampledAtImport": 2,
"sharedParametersLeft": 1,
"referencedResponsesLeft": 1,
"bodiesNotWritten": 2,
"rowsNotDeclared": 1,
"operationsEdited": 0,
"vocabularyNotWritten": false,
"secretsOmitted": 2,
"requestsOnlyInExtension": 0,
"operationsAdded": 0,
"boundMode": "contract" // "" for a skeleton
}
}
Every count is present, zeros included: "0 requests with no operation" is how a bound export states that it carried everything, and a body that omitted its zeros would read as complete whether or not it was.
mode - what a bound export may write. contract, the default, treats the
stored document as the API's contract and writes only what the next three
paragraphs describe. full writes everything the collection holds, into the
document's own dialect (Swagger 2.0 included): each request's name (as
summary, only where it differs from the name an import would read) and
description, a parameter for every Params or Headers row the operation does not
declare (a query stated only in the URL included, since the write derives its
rows, issue #3551; 2.0's type and x-example in a 2.0 document), the body as the media
type's example (2.0: an in: body or formData parameter, added only where
the operation declares none), the auth wherever the operation does not already
state it (a scheme the document declares with the same credential is reused,
otherwise one is added), saved examples (2.0: the response's examples map), a
new operation for every request the document never declared (operationsAdded;
a new operation in 3.0 or 2.0 with no saved example gets a default response,
which those dialects require), the collection's name, description, base URL and
auth at the root, and the x-vayu-* extensions below. It still never rebuilds:
schemas, $refs and every member Vayu does not model stay as they were, and a
request nobody edited writes nothing new into the standard members - an
unedited export in full differs from the stored document only by its
x-vayu-* keys. A skeleton ignores mode. Anything else is a 400.
A request's :name path variable is an OpenAPI path parameter (issue
1764): wherever a URL becomes a path, a whole :name segment is written¶
{name}, as a whole {{name}} segment is, and its path row's value is the
parameter's example. A path row is never declared in: query, and
x-vayu-request.params keeps each row's in (and a Postman type), so a
re-import gives the path row back. A segment with a suffix (:name.json) is left
as written, as {{name}}.json is.
A bound export patches the stored bytes, never rebuilds them. Operations no
request claims are removed (and a path left with no operations goes with them),
a declared parameter whose request row carries a value gets it as example (a
declared in: path parameter reads the request's path row of that name, issue
1764; a credential row's value is not written, see "Secrets never leave"), and stored examples become response examples - one as example, several as a named¶
examples map. Everything else - info, tags, vendor extensions, security,
components nothing references - is carried through by simply not being visited,
and the dialect is left as it was.
It adds, and never removes what the document declares (#1442). A media
object already answering with an examples map keeps every entry it had and
gains one; a single example is replaced by the one value that would replace
it, and moves into the map under the key example when a second example has to
go somewhere. A response that is a $ref is left bare and counted as
referencedResponsesLeft: a Reference Object admits no siblings in 3.0, so a
content written beside it is ignored by conformant readers and rejects the
document at a validator, and the component it names is shared with every
operation that references it. An example whose value the document already
declares is counted as examplesAlreadyDeclared and written nowhere, and an
imported example (origin: import) for a media object that declares no
example at all was sampled off that response's schema at import, so it is
counted as examplesSampledAtImport rather than written back as though the API
had stated it; where the document declares no such response either, the status
is not documented from it at all, because putting back a response the contract
dropped is not this export's to do. Values are compared as values, so an example
whose members are stored in another order than the document writes them is the
same example. An export of a spec-origin collection nobody edited is therefore
the document it was bound to, structurally unchanged.
In contract mode, the edits it does not write are counted, not silent.
It writes parameters and examples: a request body is bodiesNotWritten, a Params
or Headers row the operation declares no parameter for is rowsNotDeclared
(Authorization and Content-Type excepted - OpenAPI states them as security
and as the body's media type), and a request whose method or path no longer
matches the operation it is stamped as is operationsEdited - its values still
land, in the operation the document declares. A concrete path that fills the
operation's template (/users/1 for /users/{id}) still matches, by the rule
the matcher stamped it with, and is not counted; neither is one under a server base
path the document declares (/v1/users/1 with servers: [{url: /v1}], or a 2.0
basePath). A parameter the operation declares
by $ref, or one the Path Item declares for every method under it, is declared:
its name is read through the reference, so a row that has a home is never
counted as one the document has no place for, and sharedParametersLeft is what
says its value was not written.
A Swagger 2.0 document is the one partial case of contract mode, reported
as vocabularyNotWritten: operations nothing claims are still removed, but
nothing is written into an operation. full writes 2.0's own vocabulary.
A skeleton invents nothing. {{variable}} tokens are written as they stand
in paths (resolving them would export one machine's environment as though the
contract named it); a {{baseUrl}} server gets a real default when the
collection's own baseUrl variable has a value - written as the single-brace
{baseUrl} OpenAPI's Server Variable syntax expects, with that value as its
default - and the bare double-brace token otherwise, since an undeclared
single-brace variable is invalid OpenAPI. A path segment that is exactly one
token becomes the OpenAPI {petId} it came from, every Params and Headers row
(a query written only in the URL has its rows, issue #3551) is declared without a required it was never given but carries its toggle
explicitly as x-vayu-enabled (neither a value nor its absence says whether a
row is on), and a body or response is described only where there is a stored
example to read a shape off - carrying a description that says the shape is
derived. A JSON body holding a {{variable}} token is not valid JSON on its
own, so it is written as the text it is and read back the same way, byte for
byte, rather than re-quoted into a JSON string.
It carries what OpenAPI can name, for the modes it has names for (#1441).
A folder becomes a tag named by its full path (Users/Admin), described by
the folder's own description and declared once at the document root and on
every operation under it. Auth becomes components.securitySchemes plus a
security requirement - basic and bearer as http, an API key as apiKey,
OAuth 2 as oauth2 with the flow the request uses - at the document root for
the collection's own auth and on the operation only where a request's differs
from it. An inherit request is resolved the way POST /compose resolves it,
through its folders (the nearest one with a credential, noauth ending the
walk), so a request under a folder with its own auth states that folder's
scheme; an explicit no-auth request is security: [], one left to inherit gets
no override, and a mode with no OpenAPI name (digest, aws, ntlm) gets no
security at all. A body is written as the example another tool can send: JSON
and JSON-RPC as JSON, GraphQL as the {query, variables} envelope a
GraphQL-over-HTTP server receives, XML and text as the text they are, a form as
its fields (file parts format: binary) with the enabled text values as the
example, a binary body as one file's bytes (type: string, format: binary, no
example) - filed under the media type an enabled Content-Type row names
(application/vnd.api+json) rather than the mode's generic one; a binary body
with no such row is filed under its file's own contentType, else
application/octet-stream. What the
standard members cannot state exactly travels in x-vayu-request and
x-vayu-collection (below), so every one of these reads back as it was.
x-vayu-request and x-vayu-collection carry the rest of the collection
(core/vayu_extensions.hpp). A skeleton writes them always, a full bound
export too; contract mode writes neither. On an operation, x-vayu-request
holds the request as the UI does: name, method, url (verbatim, {{...}}
and all), order, the folder path it is filed under, every Params and Headers
row as typed (Authorization and Content-Type rows, toggles, duplicates and
all), the body in its own mode, the auth exactly as set (inherit included),
the non-default settings (followRedirects, maxRedirects, timeout,
httpVersion, verifySSL, stream), every saved example with its headers and its origin
("user" or "import", #2430; one that is neither is an unreadable example,
and a document with none, as an older Vayu wrote, imports as "import"), and
the mock mode with the index of a fixed target. At the root,
x-vayu-collection holds the
collection's variables (baseUrl included), auth and dataSchema, every
folder (path, order, description, variables, auth, elements, empty
folders included; order shares its parent's space with the requests'
x-vayu-request.order, #2535, so a request between two folders imports
there), and the requests no operation can hold - a URL with no path, or a
second request on a method and path another already claimed - counted as
requestsOnlyInExtension (and under requestsWithoutPath /
duplicateOperations, which say why). Another tool ignores both keys; Vayu's
importer reads them back (see POST /import/parse).
Secrets never leave. This export has no includeSecrets: every token,
password, API-key value, client secret, AWS key and variable marked secret, at
every level either key writes, is written as "" and counted as
secretsOmitted - except a value that is one {{variable}} reference and
nothing else, which names where the secret lives without being one. The auth
modes kept as a config bag (AWS, digest, NTLM, Hawk, OAuth 1.0, EdgeGrid, JWT,
OAuth 2.0's own config) are blanked by an allowlist of the members known to
describe the auth, so a member no list has heard of (Insomnia's IAM
secretAccessKey) leaves blank too. OAuth 2.0's extra request parameter lists
(tokenParams, authorizationParams, refreshParams) are redacted per row: a
row's key, enabled and sendAs stay, and its value is blanked when the key
names a credential (client_secret, client_assertion, password,
Authorization, X-Api-Key, the other names below), so an audience row
leaves intact; a row with no non-empty string key, and any member of a row
beside those four, is blanked whole. A credential outside an auth block is blanked by name wherever
it is written:
- a header row whose name is sensitive (
Authorization,Proxy-Authorization,Cookie,Set-Cookie,X-Api-Key,X-Auth-Token,X-CSRF-Token, the other names the logger redacts) or is the header the API-key auth in force names - the request's own, or the one its folders resolve to when it inherits - inx-vayu-request.headersand in the parameter that mirrors the row; - a query parameter by the narrower name set of the Params table (the same
names less the generic
codeandkey, plussecret,signature,x-amz-signatureand the like, plus an API-key auth's own parameter), inx-vayu-request.params, in the parameter'sexample(a:namepath row included) and inx-vayu-request.url's query and fragment; - the password of a URL's
user:pass@(the user name stays), inx-vayu-request.url, in a skeleton'sservers, and in abaseUrlvariable (collection or folder) and the server-variable default made from it; - the response headers of a saved example in
x-vayu-request.examples, by the header names (aSet-Cookierow, in full). A response's headers are never a standard member, so nothing else carries them.
The row and its key stay, the value is "", and a parameter whose value was
withheld is still declared with no example - a bound document's own example
for it is neither replaced by the credential nor erased. A value is kept only
when it is exactly one {{variable}} reference: Bearer {{token}} is blanked,
because the text around a reference can hold a literal secret. A body is
never judged: a stored example's body, a request body and a script are written
as stored, apart from the file-part rule below.
secretsOmitted counts each withheld value once wherever it is written: a
header row and the parameter that mirrors it, a URL's query and the Params
rows, and a server and the URL it was read from are one credential. A
contract export, which writes no x-vayu-request, counts a withheld row at
the declared parameter whose example it would have filled; a credential row no
operation declares was never going to be written, so it is not counted
(rowsNotDeclared still counts it).
A form's file part, and a binary body's file, keep their name, declared file
name and content type, never the local path they were read from (src). A
path a hand-edited x-vayu-request does carry is read back as written, and
sent only once picked or under an allowed folder; an unresolved it states is
dropped.
x-vayu-elements carries a request's or the collection's whole elements
array verbatim, the same vendor-extension convention x-vayu-enabled already
established - never a standard OpenAPI field, so writing it is never
"rewriting the user's contract". A skeleton export writes it on every
operation and at the document root whenever the corresponding elements array
is non-empty; a bound export writes it on an operation the document already
declares - in contract mode only into a 3.x document (nothing is written into
a Swagger 2.0 document's operations at all), in full mode into either, and at
the root. The importer reads it back
verbatim, validated against the live element registry - a document hand-edited
into an invalid array is not applied and is counted under elements_invalid
in meta.skipped (see POST /import/parse) rather than
reaching the stored request. Not read on the sync/diff path
(POST /specs/diff / POST /specs/sync): DraftRequest, what that path
compares a stored request against, deliberately excludes scripts and auth so a
re-sync never silently overwrites what a user edited locally, and an element
can carry a script.
x-vayu-mock carries a request's mockResponseMode (issue #1649) the same
way x-vayu-elements carries its elements - written only when the mode is
not "first", the default every unconfigured request already has, so an
operation with no mock opinion gains no key at all. {"mode": "random"} needs
no target; {"mode": "fixed", "example": "<key>"} names the examples map
key (or the doubled key a name collision suffixed, add_named_examples's
usual rule) the chosen example was written under, resolved by value rather
than assumed - a target this export could not itself write (a truncated body,
no recorded media type, a response the document does not declare) is the same
"nothing to name" case as the mode staying "first", and gets no key either.
Gated like x-vayu-elements: contract mode writes nothing into a Swagger
2.0 document's operations. The importer reads it back
next to x-vayu-elements, matching example against the imported example
that carries the same OpenAPI examples map key (the engine-side-only
specExampleKey provenance field, issue #1457) and setting
mockResponseMode / mockExampleId on the imported request; a key the
document no longer has an example for degrades the way elements_invalid
does - counted as mock_example_missing in meta.skipped and left on
pick_example's own "first" default rather than naming a target that is
not there. Not read on the sync/diff path, for the same reason
x-vayu-elements is not.
Errors: 400 for a missing or empty collectionId, a format other than
json/yaml, or a mode other than contract/full. 404 when the collection does not exist. 409 when the
collection's binding names a document that is not stored, or when the stored
bytes will not read as an OpenAPI object - the export refuses rather than
falling back to a skeleton, which would silently replace the document the caller
believes they are updating with one that drops everything Vayu does not model.
POST /specs/sync¶
Apply a re-fetched document to the collection bound to it, in one transaction: the document is stored, the binding moves to it, and the requests the caller selected are created, updated and deleted together. Half of that landing would leave a collection bound to a document its requests do not reflect, which is the state the binding exists to make impossible - so it is refused structurally rather than reported afterwards.
Deliberately not part of POST /import/apply: that route only ever creates,
which is what lets it own every id and validate a payload with nothing stored
behind it. A sync updates and deletes rows that already exist.
Request:
{
"collectionId": "col_9a1f...", // Required; must be bound to a spec
"spec": {
"content": "{\"openapi\":\"3.1.0\", ...}", // Required, non-empty, at most maxSpecDocumentBytes
"sourceUrl": "https://api.example.com/openapi.json" // Optional; null for a file or a paste
}, // Both indexes are derived - see POST /specs
"policy": "safe", // Optional - apply the safe ticks and state no rows.
// Mutually exclusive with the four sections below.
"collections": [ // Optional - tag folders to create
{"tempId": "t_col", "name": "pets", "parentId": "col_9a1f..."}
],
"create": [ // Optional - operations the document added, or declined ones ticked
{"tempId": "t_req", "collectionTempId": "t_col", "name": "Get a pet",
"method": "GET", "url": "https://api.example.com/pets/{{petId}}",
"specOperation": {"operationId": "getPet", "method": "GET", "path": "/pets/{petId}"}}
],
"update": [ // Optional - merge-patch by id
{"id": "req_1234...", "name": "List pets", "specOperation": {...}, "examples": true}
],
"delete": ["req_5678..."] // Optional - request ids
}
Response:
{
"idMap": {"t_col": "col_bb21...", "t_req": "req_cc34..."},
"specId": "spec_dd45...",
"specHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"syncedAt": 1730000000000,
"created": 1, "updated": 1, "deleted": 1,
"skipped": {"requests": 2, "fields": 3, "deletions": 1, "declined": 1} // Only for a `policy` call - see below
}
policy is the alternative to stating rows (issue #871). "safe" - the
only one - is core::safe_spec_apply, the same answer
POST /specs/diff reports per entry as safe /
safeFields: every operation the document adds, every field it moved that
nobody here had edited, no deletions, none of the operations a person declined
by deleting their request (issue #3031), and a request whose bound document
could not be read left alone whole. The engine works out the rows, mints the tag
folders an added operation needs (matching an existing direct child by name,
creating one at most once per call), and writes them through everything below -
the same validation, the same id minting, the same transaction. It exists
because those rules used to live in the renderer alone, which put applying a
drift out of reach of every caller that is not the Spec tab: electron/ may not
import src/, so an MCP sync_spec would have needed a copy of the one
judgement whose silent failure destroys a person's work.
Sending policy together with collections, create, update or delete is
a 400: there is no reading of "the safe ticks, plus these" that is not a
guess. A caller that wants anything the policy declines - a deletion, a field
somebody edited - states the rows itself, which is what the app does the moment
a user changes a tick.
skipped comes back only for a policy call and counts what it refused:
requests left untouched entirely, fields the document moved that were not
written (whether their request was skipped whole or applied around them),
deletions not made, and declined operations not re-created. An explicit payload gets no such key - nothing was
declined, because the caller chose the rows. It is reported for the reason the
diff bounds its buckets rather than dropping entries: a call that answered only
with what it wrote would read as "applied the drift", and the part it did not
apply is exactly the part somebody has to decide about.
Five rules the payload cannot opt out of:
- A
deletehere is permanent - it does not go to the Trash (issues #988, #1046). Every other delete in the engine is soft: the row is stamped and restorable. A sync is not a person removing a request, it is a reconciliation to a document, and the two differ in where the decision is made -POST /specs/diffreports every removal before anything is written, the app renders them as ticks the user unticks one by one, andpolicy: "safe"refuses deletions outright, so a deletion here is one a caller stated after being shown it. Leaving those rows stamped instead would put the operations a document no longer declares back in the trash on every sync, where restoring one re-creates a request the document cannot explain. The rows and the examples they own are removed in the sync's own transaction. A caller that wants the deletions recoverable omits them from the payload and issuesDELETE /requests/:idper row, which is soft. - The bound subtree is the boundary. Every request an
updateor adeletenames, and every collection a created request lands in, must be the collection being synced or one beneath it. Anything else is a400naming the item - without this the route would be a way to delete any row by id. A sub-collection bound to a different document (and everything beneath it) is outside the boundary (issue #3034): its requests belong to that document's contract, so a sync of this one cannot update or delete them, and a diff does not list them. A sub-collection bound to the same document is inside. - The engine mints every id, as
/import/applydoes: new rows are named bytempIdand translated throughidMap, and a bodyidis a400. examplesis a decision, and the rows are the document's (issue #869).trueon an update refreshes that request's imported examples from the document this call is storing; absent (orfalse) leaves every example alone. A created request always gets the responses its operation documents, soexampleson acreateitem is a400- as is a list on an update, which is what a caller sent before this and what let a payload write an example for a response no document describes. A refresh whose request records no operation of the document being stored is a400too, rather than a silent no-op. Rows withorigin: "user"(issue #588) always survive; the replacements take the block the replaced rows occupied, so a saved example never loses its position - "the first example" is what a mock server answers with. An operation whose documented responses were removed refreshes to no rows, which is how the last import's examples go. An example whose status the user deleted is not written back either (issue #722) - the delete left a tombstone and the refresh skips that status, so a sync of any field cannot undo it. The identity is the status, not the name, because a name carries the document's response description and moves when the document rewords it.- A request cannot be moved here.
collectionIdinside anupdateitem is a400; usePUT /requests/:id. - Creating a declined operation takes the decline back (issue #3031). A
createitem whosespecOperationnames the operation adeclinedentry stands for - followed into the document being stored by the diff's own identity rule - forgets that record in the same transaction, so ticking the entry is the user changing their mind and a later delete of the new request records afresh. The deletes indeleterecord nothing: the document dropped those operations, nobody declined them.
Errors: 404 when the collection does not exist. 400 when it is bound to
no spec, when policy is not "safe" or arrives beside a row section, when a
section is not an array, when a payload item is malformed (with
error.item naming the tempId or the request id, as /import/apply does), or
when the document is over maxSpecDocumentBytes - the same helper POST /specs
uses. 409 when an update names a request that no longer exists: nothing about
the payload is wrong, the ground the diff was computed against has moved, and
re-checking is what the client should do. A delete naming a request that is
already gone is not an error - that is the state the caller asked for.
Nothing is written unless all of it is.
Reorder¶
POST /reorder¶
Reposition collections and requests in one atomic batch - the write path behind a drag-and-drop reorder or a cross-folder move. One drop is one call, one lock scope and one transaction: the batch validates, stages and commits under a single acquisition of the engine's database lock, so nothing partial survives a rejection and no concurrent write - a create computing its append slot, a conflicting batch, a cascade delete - can land between what this batch checked and what it wrote.
Request:
{
"normalize": [
{"parentId": "col_1234567890"}
],
"moves": [
{"type": "request", "id": "req_1", "order": 0, "collectionId": "col_2"},
{"type": "collection", "id": "col_3", "order": 1, "parentId": null}
]
}
Both arrays are optional (absent or null means none); an empty batch is a
200 that writes nothing.
moves - each entry names one row and the position it takes:
| Field | Rule |
|---|---|
type |
"collection" or "request"; anything else is a 400 |
id |
Non-empty string naming a stored row of that type |
order |
Required, an integer from 0 to 2147483647. Not a float, not negative, not past the column - this endpoint writes dense positions, and each would be a silently truncated, unreachable or wrapped slot. Anything else is a 400, e.g. Invalid move at index 0: 'order' must be an integer from 0 to 2147483647 (got 2147483648) |
parentId (collection) |
Absent keeps the current parent; null or "" moves to the root; any other string moves under that collection, which must exist; anything else is a 400 naming parentId |
collectionId (request) |
Absent keeps the current owner; a string moves to that collection, which must exist |
A row may appear in moves at most once - two positions for one row is a 400
naming it, not a last-writer-wins accident of iteration order.
normalize - each entry names a parent, and its children are
renumbered dense 0..n-1 in the sibling order before any move
applies. The children are the parent's sub-collections and its requests as one
list (#2535), so a tie across the two kinds comes out as distinct numbers with
the sub-collection first. An entry is {"parentId": <collection id>}, or
{"parentId": null} ("" reads the same) for the root collections (the roots
hold collections only). The named collection must exist, and parentId must be stated rather
than omitted, so a renumber can never land on a scope the caller did not mean.
The per-kind shapes engines before #2535 took, {"type": "collection",
"parentId": ...} and {"type": "request", "collectionId": ...}, are a 400
naming the shape above: renumbering one kind alone would leave it tied with the
other kind's slots.
Normalization exists for the first drop into a collection whose rows predate
explicit orders: every row sits at 0, so its displayed position lives only in
the tiebreak and there are no slots to shift into. Materializing that order in
the same batch is what keeps the other siblings from appearing to jump; a
parent with every row at 0 comes out with its sub-collections at 0..m-1 and
its requests after them, the order the tie rule already showed. It is idempotent
- a scope already dense writes nothing at all.
Where a row is named by both lists, the move wins.
A move out of a spec contract declines the operation (#3446), the rule
PUT /requests/:id applies to one request, with the same
meaning of out. A request that records an operation (specOperation) and that
the batch leaves outside its contract comes back with specOperation: null,
and the operation is recorded as declined under the binding it left, in the
batch's transaction. A moved collection does this for every stamped request
beneath it, as a parentId sent to
PUT /collections/:id does (#3470). The binding after and the contract are read against the tree the
batch writes, so a request moved into a folder the same batch moves away is
judged by where the folder lands. A move within one contract keeps the stamp,
and so does moving the bound collection itself. Each request this clears is in the
response, a request whose position did not change included.
Validation is complete before the first write. Entry shapes, the existence of
every named row and owner, and the acyclicity of the post-move collection
graph are all checked first; a failure is a 400 naming the offending row with
nothing written. The cycle check reading the post-move shape is what makes two
reparents that each look legal alone (A under B and B under A) a
deterministic rejection rather than a race. The same pair sent as two
PUT /collections/:id calls is caught as well - each update holds its read to
its write - but one at a time, so the first reparent is already committed when
the second is refused; the batch refuses both and writes nothing.
That rejection is deterministic because the check and the commit share one lock
scope: two such batches arriving concurrently are serialized whole, and the
second revalidates against the first's committed graph rather than against the
shape both of them read. The rows are written as updates, never inserts, so a
batch whose row was deleted after it staged fails with a 409 naming the row and
writes nothing at all - it never re-creates the deleted row.
Response: the rows as written, in the same serialized shape a list entry carries - not an acknowledgement. A client that drew the drop optimistically settles its caches on these, so a normalization the engine performed is visible without waiting for a refetch.
{
"collections": [],
"requests": [
{"id": "req_1", "collectionId": "col_2", "order": 0, "name": "Get users", "...": "..."}
]
}
Errors: 400 for any malformed entry (a per-kind normalize entry
included), a row or owner that does not exist, a duplicate move, a cycle, or a
batch over 10000 entries. 409 if a staged row is
gone by the time the batch commits. In every case nothing at all was written.
Body that is not JSON or not an object is also a 400.
Import¶
POST /import/fetch¶
Fetch a remote collection or spec by URL, server-side, so the app can import a
resource that browser CORS would otherwise block. The engine proxies the GET
via libcurl and returns the raw body and content type.
Request:
The url must be a string whose scheme is http or https, in any case
(see URL schemes).
maxBytes is the caller's bound on the response, and the caller states it
because this route is one proxy for every import format - a Postman or
Insomnia export rides it exactly as an OpenAPI document does. Bounding it by
maxSpecDocumentBytes would refuse a collection that imports today with a
message naming a setting that governs nothing about it, so the callers that
are fetching a spec ($ref bundling and spec re-fetch) pass that live cap
themselves and the rest pass nothing.
- Absent or
nullmeans the engine's transport ceiling, 256 MiB. So does a larger value: a bound over the ceiling is clamped to it rather than refused, becausemaxSpecDocumentBytescan be raised to 100 MiB and an import the setting allows must not be turned into a400. - Anything that is not a positive integer -
0, a negative, a string, a fraction - is a400. It is not rounded into a bound the caller did not ask for. - The bound is on what is read, not on what is returned: the transfer is cut off as soon as the body grows past it, whether the server declared a length or not, so nothing buffers the whole document first. A declared length is what the refusal names as the size.
A fetch is bounded by a stall, not by a total (issue
#882). This route used to inherit
the 30-second timeout_ms every request carries, which bounds a download's
size rather than its health: 10 MB needed better than 340 KB/s merely to
arrive, and the failure read Operation timed out after 30001 milliseconds with
4177920 out of 6296254 bytes received for a transfer that had never once
stopped. It is now abandoned only after
constants::import_fetch::STALL_TIMEOUT_MS below
STALL_FLOOR_BYTES_PER_SEC - so a slow link finishes, slowly, and a dead one
still ends. What bounds a transfer that never ends at all is maxBytes above,
which is the bound that was always meant. Connecting is bounded apart from
the stall, at the stall window capped at 30 seconds (issue #2835): the stall
window only runs once a connection is made, so a host that never completes the
handshake would otherwise hold the fetch for libcurl's 300-second default. Both
forms of the route get this: a document must not arrive on one and time out on
the other.
reference: true marks a fetch a document asked for, not a person (issue
#2364): $ref bundling sends
it, with sourceUrl set to the URL of the document the reference was found
in. A URL typed into the import dialog or a spec re-fetch sends neither field
and is fetched exactly as before, loopback and redirects included.
{ "url": "http://localhost:3000/schemas/pet.json", "maxBytes": 10485760,
"reference": true, "sourceUrl": "http://localhost:3000/openapi.yaml" }
referenceis a boolean, defaultfalse;sourceUrlis anhttporhttpsURL. Absent ornullmeans the default for either; any other shape is a400, and a malformedsourceUrlis refused even withoutreference.- No redirect is followed. A
3xxis the upstream's answer and is refused as every non-2xxone is (502The server answered HTTP 302): a hop is a target the document never named. - A loopback or link-local peer is refused unless it is the source's own.
Judged on the address libcurl connected to, so a name that resolves there
(
localhost,*.localhost, a DNS record pointing at127.0.0.1) is caught as surely as a literal. Refused:127.0.0.0/8,::1,::ffff:127.0.0.0/104, the unspecified0.0.0.0and::,169.254.0.0/16(cloud metadata lives there),::ffff:169.254.0.0/112andfe80::/10. Allowed: a peer onsourceUrl's port (its scheme default when it names none) when either the source host is itself loopback (localhost,*.localhostor a loopback address) and the peer is loopback, or the source host is the peer's address written as a literal - the only way a link-local peer is ever the source's. A source named by a host name that resolves to loopback earns nothing: that is what a rebinding DNS answer looks like. With nosourceUrl, every loopback and link-local peer is refused. - The refusal is
502Couldn't fetch the document: Cannot send this request: Vayu does not fetch a reference from a loopback or link-local address other than its source document's own host and port - not when the URL names one and not when a host name resolves to one, on both forms of the route. - The URL is judged before anything is dialled, by the same source rule: a
reference whose host names a loopback or link-local address in any spelling,
localhostor a*.localhostname is refused with the same502, and the source's own host and port stay allowed (issue #2605). - A proxy you configured is not refused. With a proxy in force the
connected peer is the proxy, so the rule passes the one the transport names
(
manual, orsystemwhen it resolved one; matched on its address and port, alocalhostproxy URL meeting any loopback address) and the URL check above is what judges the reference. Behind a proxy the engine cannot see where the proxy sends the request next, so a host name the proxy resolves to loopback is the proxy's to answer. A proxy URL with no port is dialled on libcurl's proxy default,1080(443for anhttpsproxy). environmentmode stays uncovered, as doessystemwhen it resolved nothing and falls back to it. There libcurl reads the proxy from the process environment (http_proxy,https_proxy) and the engine never learns it, so a proxy on loopback picked up that way is still refused for every reference unless it is the source's host and port. Set it asmanualto fetch references through it.- Vayu's own engine and MCP ports stay refused whatever the source (Reserved local ports); this rule is added to that one, never in place of it.
Response: 200
contentType echoes the fetched response's Content-Type header, defaulting to
application/octet-stream when absent. The response JSON is serialized with
invalid UTF-8 replaced rather than throwing, so binary or malformed content can
never turn into a 500.
Errors:
- 400 Invalid JSON: <parser message> - the request body did not parse; request body is nested deeper than 128 levels when it nests past the bound.
- 400 Invalid URL - url is missing, not a string, or names no scheme.
- 400 Invalid URL: scheme '<scheme>' is not supported - only http and
https URLs can be sent - url names any other scheme (ftp, file, ...).
- 400 Invalid 'maxBytes': must be a positive integer.
- 400 Invalid 'reference': must be a boolean.
- 400 Invalid 'sourceUrl': must be an http or https URL - also a URL that
names no host.
- 413 Refused to fetch: <detail> - the response was over the bound in force.
The detail names the bound that was applied (the clamped one, not the one
asked for) and the size when the upstream declared one.
- 502 Couldn't fetch the document: <detail> - the upstream request failed
(connection error, transport failure), or a reference's peer was refused
(see reference above).
- 502 The server answered HTTP <status> - the upstream answered, but with a
status outside 2xx. Its body is not the document, so it is not returned as
content: handed on, a 404 or 500 page would reach the format reader and
be reported as an unrecognised format.
With Accept: text/event-stream the same fetch answers as a stream
(issue #882), reporting the
download as it arrives. An 8 MB spec behind a URL is otherwise a client with
nothing to draw: the buffered form above cannot say a word until libcurl holds
the entire body, and the wait is on the upstream download, so no amount of
streaming between engine and client would help.
Three events, and the last one is always terminal:
| Event | Data | Meaning |
|---|---|---|
progress |
{"received": 262144, "total": 8388608} |
Bytes buffered so far. total is the upstream's Content-Length and is null when it declared none - a chunked response has no denominator, so a client shows bytes received rather than a percentage of a number nobody stated. |
result |
{"content": "...", "contentType": "application/json"} |
Exactly what the buffered form returns. |
error |
{"status": 413, "error": {"code": "error", "message": "..."}} |
The failure the buffered form would have answered with. |
- A malformed request is still the
400above, on both forms: it is decided before any of the response has gone out, while a status is still available to say it with. - A failed fetch is an
errorevent, not a status. The response headers left before the download began, so the200is already spent - which is why that event carries the numericstatusitself. The standard error body could not: itscodeis a slug, and413and404both slug to plainerror. - Progress is throttled to at most one frame per 256 KiB or 100 ms
(
constants::import_fetch::PROGRESS_EVERY_BYTES/_MS). libcurl reports every ~16 KiB write, which for a 10 MB document is ~640 frames for a bar with a few hundred pixels to cross. - Closing the stream stops the download. The engine abandons the transfer as soon as a write to the SSE sink fails, rather than reading the remaining megabytes for a client that has gone.
- Every caller that sends no
Acceptgets the buffered JSON unchanged, which is what$refbundling, spec re-fetch and the MCP tools do.
POST /import/parse¶
Parse a raw import document into the tree POST /import/apply
persists (issue #877). Reads only -
nothing is stored, so a preview costs no write.
Every format Vayu accepts, detected by content, in the order the app's dispatcher used to run its parsers in - so a document carrying two formats' keys is claimed by the same one it always was:
| Claimed by | meta.format |
|---|---|
info.schema naming v2.1.0 |
Postman Collection v2.1 |
info.schema naming v2.0.0, or info + item[] with no schema |
Postman Collection v2.0 |
_postman_variable_scope: "environment" + values[] |
Postman Environment |
_postman_variable_scope: "globals" + values[] |
Postman Globals |
_type: "export" + __export_format: 4 |
Insomnia Export v4 |
type: collection.insomnia.rest/5.x or environment.insomnia.rest/5.x |
Insomnia Export v5 |
openapi starting 3.1 |
OpenAPI 3.1 |
openapi starting 3. (any other 3.x) |
OpenAPI 3.0 |
swagger being 2.0 (string or number) |
OpenAPI 2.0 (Swagger) |
the raw text contains <jmeterTestPlan |
JMeter <version> Test Plan |
The bytes are read once, JSON first and YAML second, through the same
core::read_document behind POST /specs and
POST /specs/describe. This is the only parser: the
renderer holds none, which is what makes "exactly one reader has an opinion
about a document" true rather than nearly true. JMeter's .jmx is the one
exception to "read once through read_document": it is XML, checked on the
raw text (issue #1518, is_jmeter_document) before that reader ever runs,
since XML fails both of its formats the same way genuinely unrecognised bytes
do - see docs/app/import-collections/jmeter.md for the class mapping.
Insomnia v5 (issue #2119) is
the YAML document Insomnia 11 and later export, one per collection or
environment. It is read through the v4 mapping: the nested collection[] tree
(a children array makes a folder) and the environments object with its
subEnvironments[] are flattened into v4's resource list, so both versions of
one workspace import as the same tree and only meta.format tells them apart.
An environment.insomnia.rest/5.x document imports environments only, under
importEnvironments like a Postman environment export; with no
sub-environment its one environment is named after the document. A gRPC or
WebSocket item is counted in meta.skipped as grpc / websocket, as in v4,
and cookieJar and certificates are not imported. The member spellings are
those of Insomnia's v5 schema; a member spelled otherwise reads as absent.
Variable names are trimmed (#3251). {{ name }} looks a variable up trimmed,
and the write routes refuse a stored name that is blank or differs from its trim
(Accepted field shapes). The parse therefore trims
every variable name it reads (Postman variable[] and values[], an Insomnia
environment's data keys, a dotted nested name as a whole) and skips a row whose
name trims to nothing, uncounted, as an empty name always was. Two names that
trim alike collide and the later row wins, as exact duplicates do. An
x-vayu-collection / x-vayu-folder variables object carrying such a name is
an invalid extension piece (vayu_extension_invalid) and the standard reading
stands. POST /import writes the parsed globals through the same trimmed names.
A hand-built POST /import/apply tree is not repaired: a padded name in it is the
same 400, and the whole atomic apply fails.
A Postman variable carries its file position as createdAt (#3252). A
stored variables object keeps its keys in name order, and the app lists a scope
by createdAt (VariableValue shape), so
every row of a Postman variable[] or values[] is stamped with one clock
reading per parse plus its position in the array: strictly ascending in the
file's order, in epoch milliseconds.
Request:
{
"content": "{\"info\": {...}, \"item\": [...]}",
"importEnvironments": true,
"importScripts": true,
"fileName": "collection.json",
"sourceUrl": "https://acme.dev/openapi.json",
"unresolvedRefs": 0
}
| Field | Type | Notes |
|---|---|---|
content |
string, required | The document, verbatim. An OpenAPI import stores exactly these bytes as its spec document, so it is never re-serialized. |
importEnvironments |
bool, default true |
Off, the environments and global variables a document carries are not built and the counts report 0 - gated at parse time, so a preview shows what will actually be created. |
importScripts |
bool, default true |
Off, every script imports empty. |
fileName |
string | Display only; echoed on meta.fileName. Never stored. |
sourceUrl |
string | Recorded on a stored OpenAPI document (so a later sync knows what to re-fetch) and used to resolve a relative servers[0].url. |
unresolvedRefs |
int ≥ 0 | External $refs a bundling pass could not reach, counted into meta.skipped as external_ref. Nothing here follows a ref. |
Response: 200 - the whole import tree.
{
"collections": [ { "name": "Sample API", "description": "", "variables": {}, "auth": {"mode":"none"},
"elements": [], "children": [], "requests": [] } ],
"environments": [],
"globals": {},
"clientCertificates": [],
"meta": {
"format": "Postman Collection v2.1", "requestCount": 2, "folderCount": 1,
"environmentCount": 0, "globalCount": 0, "exampleCount": 0,
"skipped": [ { "kind": "unsupported_auth", "count": 1, "requests": ["Get user"] } ],
"nonExecutableAuth": 0, "unattachedFileParts": 0,
"unsupportedScriptApis": [ { "request": "Sign in", "names": ["require()", "cheerio"] } ]
}
}
meta.unsupportedScriptApis (Postman only, issue
#2576) is [{request, names}]:
each request, folder or collection (by its name) whose imported scripts use a
Postman script API Vayu does not run, and which ones - require() of a module
off the crypto-js / uuid / lodash / moment / csv-parse/lib/sync / xml2js / chai / ajv / tv4 shelf, script.packages, a bundled library such as
cheerio, a host global such as fetch or URL, an undefined pm.* member such as pm.cookies.set, a
console method such as console.debug, and the other rows of the table in
engine/src/core/script_api_scan.cpp (it does not scan process, window, document or alert). It is absent when empty and for every
other format, is not a meta.skipped kind, and never changes what is imported;
docs/app/import-collections/postman.md#scripts has the rules.
meta.skipped is one {kind, count} per kind the parse counted, in a fixed
kind order. requests, when present, names the requests the count applies
to, in the order the walk met them: every count an OpenAPI parse takes while on
an operation, Postman's per-request counters (and, for script_unsupported,
the folder or collection that declares the script), and Insomnia's file bodies,
unsupported auth types, cookie API keys, insomnia scripts and the resources it
cannot import. A count that belongs to the document (a second
server URL, a malformed section) has none. names, when present, names
what the count dropped, never its value: oauth2_unmapped_param, whose
names are the keys of the OAuth 2.0 request parameters a Postman parse did
not carry, and protocol_behavior_folder, whose names are the folders or
collection that declared a setting Vayu cannot apply. A Postman parse also
counts body_on_get (#2540), named under requests: a GET or HEAD whose
mapped body is not empty and whose resolved
protocolProfileBehavior.disableBodyPruning is not boolean true, a body
Postman drops before sending and Vayu sends. The parse maps the body as written.
clientCertificates is present, and only ever non-empty, from a Postman
parse (issue #1656): a
client_certificates registry candidate resolved from a request's own
certificate, in the same field shape POST /client-certificates takes
(host, port?, certPath, keyPath?, certFormat?, passphrase?). A candidate is resolved
only when it would pass that route's own check - a readable PEM pair or
PKCS#12 file, a literal (not {{var}}) host, no earlier request in this parse
already claiming a different certificate for the same (host, port) - so
resolving one is the common case only when the collection's certificate paths
are reachable from this machine, which a real-world Postman export's rarely
are (its paths name files on the exporting machine). Anything that does
not resolve counts into meta.skipped as certificate instead of appearing
here. Every other format sends no such key. See
docs/app/import-collections/postman.md.
meta.skipped is what the document declared and Vayu cannot represent, counted
per kind. The fixed kinds, in the order they are reported (ORDER in
ImportTally::items(), engine/src/core/openapi_drafts.cpp):
kind |
Counted when |
|---|---|
websocket, grpc |
An Insomnia resource that is a WebSocket or gRPC request, which has no Vayu request shape |
api_spec |
An Insomnia design document (api_spec resource) |
unit_test |
An Insomnia unit test or unit test suite |
file_body |
A whole-file body (Postman file, Insomnia binary, an OpenAPI application/octet-stream or format: binary body), imported as a binary body whose file is still to choose |
malformed_item |
A Postman item[] or event[] entry that is not an object, or a saved response that is not an object, whose numeric code is not an integer from 200 to 599, whose body is over 1 MiB, or that comes past the request's first 100 (the request still imports) |
unsupported_method |
A Postman custom HTTP verb (imported as GET), or an OpenAPI trace operation (dropped; HttpMethod has no TRACE) |
malformed_spec |
An OpenAPI path item, parameters list or response whose shape the specification does not allow, stepped over so the rest of the file still imports |
example_no_status |
An OpenAPI response key that is neither default nor a status from 200 to 599 (a 2XX wildcard, a 1xx interim response, junk) |
example_no_media_type |
An OpenAPI response that documents a body (a 3.x content map with entries, a 2.0 examples map or schema) and yields none: no JSON type that yields one, and no declared string or text-family (text/*, */xml, */html) example, a media range (a key containing *) never counting; the example imports without a body (#3424) |
default_response |
An OpenAPI response keyed default - conformant, and counted as information rather than as a loss |
external_ref |
A $ref into another file that a bundling pass could not reach (the request's unresolvedRefs) |
duplicate_operation_id |
An OpenAPI operationId that an earlier operation already declared; the first keeps the id |
webhook_operations |
An operation under a 3.1 top-level webhooks entry: it describes a call the API makes to the user, not a request Vayu can send |
deprecated_operation |
An OpenAPI operation declared deprecated: true; the request model has no such flag, so it imports like a current one |
cookie_param |
An OpenAPI parameter declared in: "cookie", which has no row to land in |
unmapped_body |
An OpenAPI requestBody declaring only media types with no Vayu body mode and no binary schema, one per operation |
unresolved_base_url |
servers[0].url still holds a {variable} with no default, or is relative and the document has no source URL; it is kept as written |
no_server_url |
The OpenAPI document names no server URL, so no {{baseUrl}} variable is created |
servers_dropped |
An OpenAPI 3.x document with more than one servers entry: only servers[0] becomes {{baseUrl}}, and the count is the entries past the first |
unsupported_auth |
A Postman auth block whose type the schema does not define, or an Insomnia authentication.type with no Vayu mode (asap, netrc) or that is not a string; either way it imports as no auth, never inherit (an Insomnia folder's ends the inherit walk as noauth) |
security_unmapped_or |
An OpenAPI operation whose security lists more than one alternative requirement; it stays inherit |
security_unmapped_and |
An OpenAPI operation whose security requirement names more than one scheme at once; it stays inherit |
security_unmapped_scheme |
An OpenAPI operation whose security names a scheme the document never declares; it stays inherit |
security_unmapped_mutualtls |
An operation's security names a mutualTLS scheme, which has no Vayu auth mode; it stays inherit |
security_unmapped_openidconnect |
An operation's security names an openIdConnect scheme, which has no Vayu auth mode; it stays inherit |
security_unmapped_type |
An operation's security names a scheme of any other type with no Vayu mode (an http scheme other than bearer or basic, or no readable type); it stays inherit |
security_unmapped_apikey_cookie |
An operation's security names an apiKey scheme with in: "cookie"; Vayu's API-key mode has only header and query placements, so it stays inherit. An Insomnia API key with addTo: "cookie" that has no place to go is the same kind: a folder's (imported as noauth, ending the inherit walk) or the workspace's (none), which have no header row to hold it, and a request's with no key name, which has no cookie to write. Folders and the workspace are unnamed |
apikey_cookie_header |
An Insomnia request's API key with addTo: "cookie", imported as no auth plus a Cookie: key=value header row (merged into an enabled Cookie row the request already has) - a mapping the user may want to check, not a loss |
oauth2_dropped_field |
A Postman OAuth 2.0 block carrying a pre-fetched accessToken beside an explicit grant configuration; the token is not imported |
oauth2_state_regenerated |
A Postman OAuth 2.0 block with a fixed state; Vayu generates its own per authorization attempt |
oauth2_unmapped_param |
A Postman OAuth 2.0 extra request parameter that was not carried, its key under names |
url_without_raw |
A Postman URL object with no raw form, assembled from its host, port and path - a mapping, not a loss |
variable_metadata |
A Postman variable type with no Vayu counterpart ("any", a custom string), or an environment or globals variable's description |
disabled_body |
A Postman request body whose own disabled is true; it imports as no body rather than sending what the user switched off |
certificate |
A Postman request's own certificate that did not become a registry candidate (no cert.src / key.src, an unreadable file, a {{var}} host, or a conflict for the same (host, port)), plus the candidates left unticked in the preview |
proxy_config |
A Postman request's own proxy override; there is no per-request proxy to import it into, so this count is permanent |
protocol_behavior |
A Postman request's protocolProfileBehavior setting that Vayu stores for the export but does not apply, or host / content-length in its disabledSystemHeaders |
protocol_behavior_folder |
The same, declared on a folder or the collection: counted once per declaring node, its name under names |
body_on_get |
A Postman GET or HEAD with a non-empty body whose resolved disableBodyPruning is not true: Postman does not send it, Vayu does |
script_unsupported |
A Postman enabled event with a script.src, or script text under a listen other than prerequest / test, which has no element to become |
script_unsupported_insomnia |
An Insomnia request, folder or workspace whose imported, non-blank script uses the insomnia object, which Vayu does not define; the script is kept and throws when it runs. Counted once per owner, only with importScripts on, the owner under requests |
Three kinds are counted but are not in that order, so they come after it, in
first-encountered order: elements_invalid (an elements array, from a
document a Vayu export wrote, that fails the element registry's validation and
is not applied), mock_example_missing (a stored mock setting that names an
example the document does not carry) and vayu_extension_invalid
(a piece of an x-vayu-* extension that fails its check; the standard reading
stays in place). Not every kind is a
loss: default_response and url_without_raw count a mapping
the import made rather than something it dropped (see
docs/app/import-collections/postman.md), and so does file_body: a
whole-file body (Postman file, Insomnia binary, an OpenAPI
application/octet-stream or format: binary body) imports as a binary body
naming the file, and the count, with its requests, says which bodies have a
file to relink or choose. Every file reference an import writes - a binary
body's file, a form-data file part - carries the path the document named,
which the engine sends only once the file is picked again or lies under an
allowed folder. POST /import/parse answers each with the derived
unresolved (the trust rule):
true for a path this machine would refuse, so the preview can offer to allow
its folder. A reference with no path ("src": "") imports as no file chosen;
form parts in that state are counted in meta.unattachedFileParts. An import that loses something and
says nothing is the defect this list exists to prevent, so a format with
nothing to report answers [] rather than omitting the field. A JMeter
import's kind is not limited to this list (issue #1518): a .jmx class
this parser has no element-kind mapping for is counted under its own literal
class name (CookieManager, CSVDataSet, ...), since JMeter's own class list
is open-ended - ImportTally::items() emits every kind it was given a count
for, the enumerable ones first in the fixed order above, anything else after in
first-encountered order. A JMeter ThreadGroup whose threads, ramp-up,
duration or loops are not the defaults is counted as ThreadGroup_profile
(one per group), and the item's names lists one line per group with the
values as written, e.g. Users: 10 threads; ramp-up 5s; 3 loops, so a client
can show what to set on the load run; a setUp or tearDown group is counted
under SetupThreadGroup / PostThreadGroup, once per sampler left out
(docs/app/import-collections/jmeter.md). A JMeter request with both a connect
and a response timeout is counted as Timeout_total (one per request, its name
in names) because Vayu keeps one total timeout and adds them, and a timeout
that is not a number (a ${var}) as HTTPSampler_timeout_unrecognised.
meta.folderStrategy (tags / paths / mixed) is present only when an
OpenAPI import built folders, since a document that declares no operation tags
gets a tree it never spelled out.
A document Vayu exported reads back as the collection it came from. An
operation's x-vayu-request and the root's x-vayu-collection (see
POST /specs/export) are applied over what the standard
members produced: the request's name, method, URL, rows, body, auth, settings
and saved examples, and the collection's variables, auth, data contract and
whole folder tree. With x-vayu-collection present the document states its own
tree, so folders nest as it says, each request is filed under its
x-vayu-request.folder, folders and requests take their stored order (below),
a request with none stays on the
root (no folder named after its path, and no folderStrategy), and the
requests no operation could hold are created too. A document is a file anyone
can edit, so none of it is trusted: every piece is checked against what the
write routes accept before it replaces anything, and a piece that fails is
dropped, counted as vayu_extension_invalid, and leaves the standard reading in
place - never a refused import. Neither key is read on the sync/diff path, for
the reason x-vayu-elements is not.
A folder or request draft may state order, its position among its
parent's sub-folders and requests, which share one order space
(#2535). A Postman parse states it on every one: the item's position in its
parent's item[], so the collection keeps the order Postman runs it in. A
JMeter parse (#2573) states it the same way on every sampler and controller
folder: its position among the parent's enabled elements in the plan's tree,
one count across both kinds, which a ThreadGroup shares with the parent it
flattens into. An Insomnia parse, v4 or v5 (#2573), states it as each folder's and
request's rank, 0..k-1, among the parent's siblings that import, ordered by
ascending metaSortKey (v5's meta.sortKey) with ties in document order; a
parent where any such sibling has no numeric key states none, so its folders
come first. A Vayu-written OpenAPI document states each request's x-vayu-request.order and
each folder's x-vayu-collection.folders[].order; one written before folders
carried an order states none, and its requests then follow its folders as
they did. No other format states one. The flattening into
POST /import/apply (POST /import, and the app's apply
of a previewed parse) numbers each parent's children 0..k-1 in one sequence:
by stated order, a draft stating none placed as though its parent listed its
folders first and its requests after them, and a folder first on a tie. The
preview tree lists them in the same order.
Errors:
- 400 Invalid 'content': must be the document's text, and
400 Invalid 'content': an empty document is not an import.
- 400 Unrecognised format - readable, and no format claims it. Kept as its
own sentence: "Vayu does not read this kind of file" and "this file is broken"
are different answers.
- 400 Couldn't read the document: <detail> - neither JSON nor YAML, with
the line named.
- 400 Couldn't read the document: this is an Insomnia <kind> export, which Vayu does not read. Export the collection instead. - an Insomnia document
that is not a collection or an environment: <kind> reads design document
(spec) for spec.insomnia.rest/, mock server for mock.insomnia.rest/,
and the type's own prefix otherwise. A collection or environment in a
format other than 5.x gets ... this is an Insomnia collection export in
format 6.0, which this version of Vayu does not read. It reads format 5.
Neither is Unrecognised format, so the app shows the sentence as written.
- 400 Malformed Insomnia export: <field> must be an array (or
an object) - Insomnia's resource list (v4) or nested tree (v5) broken
where the walk needs it, so there is nothing to walk; a v5 field is named by
its path (collection[0].children[2]).
- 400 Malformed JMeter test plan: <detail> - XML pugixml could not parse,
or well-formed XML with no <jmeterTestPlan> root.
- 400 Invalid 'importScripts': must be a boolean (and the same for
importEnvironments, fileName, sourceUrl, unresolvedRefs).
- 413 Import document is N bytes, over the limit of M (raise the 'maxSpecDocumentBytes' setting to allow more).
Body cap (POST /import, /import/parse, /import/document). The management
API buffers a request body before a route sees it, so these three routes are
bounded from the Content-Length header, before the body is read: a body over
maxSpecDocumentBytes plus half again plus 1 MiB (headroom for the JSON string
escaping of the document) answers 413 Request body is N bytes, over the limit of
M for an import (raise the 'maxSpecDocumentBytes' setting to allow more). The
limit is read live, so a raised setting applies to the next request. A chunked
body is refused with 411 like on every route (see
Request bodies). The exact check on the content string
described below still runs after the parse. A client that streams a very large
body may see the connection closed rather than the 413, since the body is not
read.
POST /import¶
Parse a document and persist it, in one call - POST /import/parse, the
flattening into temp-id'd sections, and POST /import/apply, for a caller with
no preview to show (issue #877).
This is what the MCP import_document tool wraps. The app deliberately does not
use it: a person picks which files of a batch to import and toggles two options
between the parse and the apply.
Request: the same body as POST /import/parse.
Response: 200
{
"idMap": { "c1": "col_<uuid>", "r1": "req_<uuid>" },
"meta": { "format": "Postman Collection v2.1", "requestCount": 2, "...": "..." },
"collections": 2, "requests": 2, "environments": 0, "globals": 0
}
Atomicity: the tree is one POST /import/apply transaction, so a refused
document creates nothing. The globals a Postman globals export carries are
the one write outside it, and they run last and merge: POST /globals
replaces the whole set, so running it in front of a write that can still fail
would leave a user's globals half-rewritten by an import that then failed. On a
key collision the imported value wins - the caller asked for this file's
variables, and skipping them would be a silent no-op - but the stored row keeps
its createdAt (or its lack of one), so a replaced global keeps its place in
the list (#3252). A Postman import's
clientCertificates candidates (issue #1656) are also outside the tree's
transaction, applied best-effort inside POST /import/apply itself after it
commits; a candidate POST /import/apply cannot register is skipped, never
fails the call.
Errors: every error of POST /import/parse, plus every error of
POST /import/apply (including the per-item 400s naming a tempId).
POST /import/document¶
Read a document's bytes (JSON or YAML) into a JSON DOM, through the engine's one
reader. Stores nothing and interprets nothing: this is what the bytes are,
where POST /specs/describe says what they declare.
One caller, and it is the reason the route exists: the app's ref-bundler.ts
walks a multi-file OpenAPI document to inline the files it references before
anything is parsed or stored, and finding and rewriting those $refs needs a
tree. A YAML reader in the renderer to get one was the last thing keeping a
second parser in app/src after issue #877.
Request: {"content": "openapi: 3.0.0\npaths: {}\n"}
Response: 200 {"document": { "openapi": "3.0.0", "paths": {} }} - in the
document's own key order, which is a promise a JavaScript object cannot keep (it
orders integer-like keys numerically ahead of the rest).
Errors:
- 400 Invalid 'content': must be the document's text.
- 400 Invalid 'content': <detail> - neither JSON nor YAML.
- 413 Document is N bytes, over the limit of M (raise the 'maxSpecDocumentBytes' setting to allow more).
POST /import/apply¶
Persist an entire parsed import - collections, their requests, environments, and
the OpenAPI documents they bind - in one atomic call. Items reference each other by opaque temp ids the
client invents; the engine generates every real id via generate_id and returns
the translation in idMap. A fifth section, clientCertificates
(issue #1656), is not part of that atomic tree or its temp-id namespace - see
its own bullet below.
This is what replaced ~500 sequential POST /collections + POST /requests
calls for a 500-request import, and with it the only reason those endpoints ever
accepted a client-supplied id - which they no longer do (see
The engine owns every id).
Request:
{
"specs": [
{ "tempId": "s1", "content": "{\"openapi\":\"3.1.0\", ...}",
"sourceUrl": "https://api.example.com/openapi.json" }
],
"collections": [
{ "tempId": "c1", "parentTempId": null, "name": "My API", "order": 0,
"variables": {}, "auth": {"mode":"none"},
"openapi": {"specTempId": "s1"},
"elements": [] },
{ "tempId": "c2", "parentTempId": "c1", "name": "Users", "order": 0 }
],
"requests": [
{ "tempId": "r1", "collectionTempId": "c2", "name": "List users",
"method": "GET", "url": "https://api.example.com/users",
"params": [], "headers": [], "body": {"mode":"none"}, "bodyType": "none",
"auth": {"mode":"inherit"}, "order": 0,
"examples": [
{ "name": "200 - A user", "status": 200, "headers": [], "body": "{}",
"contentType": "application/json" }
] }
],
"environments": [
{ "tempId": "e1", "name": "Prod", "variables": {} }
],
"clientCertificates": [
{ "host": "api.example.com", "port": 8443, "certPath": "/home/alice/certs/client.pem",
"keyPath": "/home/alice/certs/client-key.pem", "certFormat": "pem" }
]
}
- All five sections are optional; absent or
nullmeans "none of that kind" (the null-vs-absent rule). An empty payload is a200with an emptyidMap. - Every item needs a non-empty string
tempId, unique across the four tree sections (they share one namespace, becauseidMapis one flat map) -clientCertificatesitems carry notempIdat all, see below. Temp ids are never stored. - A collection's
parentTempIdand a request'scollectionTempIdmust name a collectiontempIdin the same payload; references may point forward, so a child may appear before its parent.parentTempIdisnull(or absent) for a root. - Every other field is the one the matching
POST /<resource>accepts, with the same defaults and the same null rule - the engine runs the same per-resource field appliers for both paths.idis not accepted here: the engine owns ID generation on this path. orderis optional, and a stated one is written as given. An omittedorderappends after the parent's existing children and then in payload order: each row gets the next slot of its parent (the per-item default cannot do this in bulk, because none of the payload's own siblings are stored yet). A parent's sub-collections and requests share those slots (#2535): the sub-collections that state noordertake them first, in payload order, and then its requests, so a request with noorderlands after its folder's sub-collections rather than tied with the first of them. The roots hold collections only. The app's importer states every order below the roots, one sequence per parent in the order the parse placed the drafts (seePOST /import/parse), and deliberately omits it on its root collections, so an import into a non-empty workspace lands after the roots already there instead of colliding with their0, 1, 2....- A request may carry
examples, an array of saved example responses. They are nested rather than a fourth section because nothing references them: they need notempId, get engine-generated ids, and so do not appear inidMap. Each entry takes the fieldsPOST /requests/:id/examplesaccepts, through the same field applier, and an entry that fails validation is a per-item400naming the request'stempId.originis among those fields: a spec or Postman import leaves it at its"import"default, which is what those rows are, and a Vayu OpenAPI export re-imported passes through theoriginit wrote intox-vayu-request.examples(#2430), so a user-saved example stays"user". An entry with noordertakes its payload position, so the stored order is the order the source file listed the responses in. - A
specsitem carriescontent(required, non-empty) and an optionalsourceUrl; itshashandfetchedAtare engine-computed and a per-item400if sent, and the size cap is the same livemaxSpecDocumentBytesthatPOST /specsenforces, through the same helper. Spec rows are written before the collections that bind them, in the same transaction. - A collection binds a spec through
openapi.specTempId(a spec in this payload, resolved through the temp-id map exactly ascollectionTempIdis) oropenapi.specId(one already stored). Sending both is a per-item400, and so is either one that resolves to nothing. The resolved value is stored asopenapi.specId;specTempIdis never persisted. The binding'sspecHashandsyncedAtare stamped by the engine from the document - the one this payload just wrote, or the stored one anopenapi.specIdnames - so an imported collection is bound to a version and its runs are measured against the contract (issue #709). AspecHashorsyncedAtthe item sends is dropped, never stored (issue #3348). - A
clientCertificatesitem is aclient_certificatesregistry candidate (issue #1656), in the same field shapePOST /client-certificatestakes (host,port,certPath,keyPath,certFormat,passphrase) -idis refused here too. Unlike every other section it carries notempId(nothing else in the payload references a certificate) and is applied after the tree's own transaction commits rather than inside it: the engine reusesPOST /client-certificates's own check-and-write, which takes its own lock, and taking it from inside the tree's transaction would deadlock. A candidate that fails that route's own checks (an unreadable file, a(host, port)pair another row already claims) is skipped rather than failing the call or naming anitemerror - the tree it does not reference has already committed by the time this section runs, and nothing in the response says which candidates landed. The engine registers every candidate it is sent: the app sends only the ones the user ticked in the preview, so an empty array registers nothing. Each registration is logged at info (http: host, port and certificate path, never the passphrase or the key), and a skipped candidate at warning. Only a Postman preview's ownclientCertificatesarray (POST /import/parse) ever populates this; every other format sends[]. - Up to 10,000 items per call (collections + requests + environments + specs + nested examples + clientCertificates - they are rows this call allocates and writes, so they count).
Response: 200
{ "idMap": { "c1": "col_<uuid>", "c2": "col_<uuid>", "r1": "req_<uuid>", "e1": "env_<uuid>", "s1": "spec_<uuid>" } }
Every tempId sent appears in idMap. Nested examples do not - they carry no
tempId to map.
Atomicity: validation runs over the whole payload before anything is written,
and the write itself is a single SQLite transaction. A 400 therefore means
nothing was persisted - there is no partial tree to clean up.
Errors: every 400 uses the standard error object, and the per-item ones add
an item key inside it (the offending tempId) so a large import can name
what broke:
Messages, by case:
- 400 Invalid JSON: <parser message> - the body did not parse; request body is nested deeper than 128 levels when it nests past the bound.
- 400 Body must be a JSON object.
- 400 Invalid 'collections': must be an array - a section was
present but not an array (same for requests / environments / specs).
- 400 Invalid collection at index 2: 'tempId' must be a non-empty string.
- 400 Invalid collection at index 0: 'id' is not accepted - the engine assigns ids; reference items by 'tempId'.
- 400 Duplicate tempId 'c1', with item: "c1".
- 400 Unknown parentTempId 'c9', with item: "c2", and the same for
collectionTempId - including a collectionTempId that names an environment
rather than a collection.
- 400 Unknown openapi.specTempId 's9', with item: "c1", and
400 Spec 'spec_...' does not exist for an openapi.specId that resolves to
no stored document.
- 400 Cycle in parentTempId references at 'c1', with item: "c2" -
a cycle (including a self-parent) in the payload's own parent graph. The
stored-tree walk that guards POST /collections cannot see this one, because
none of these rows exist yet, and a cycle makes cascade delete loop forever
(issue #79).
- 400 Missing required field: name, with item: "c1", and the other
per-field errors of the matching POST /<resource>, including a wrong-typed
field ("name": 42), which is a 400 rather than a 500.
- 400 'specFile' is not part of an import: it binds a file on this machine,
set with PUT /collections/:id, with item: "c1", and the same for
dataFile (issue #2765); null passes.
- 400 Import too large: 10001 items exceeds the limit of 10000 per call.
- 500 <detail> - the transaction itself failed; nothing was
written.
Export¶
POST /export/postman¶
A collection and everything beneath it as a Postman Collection v2.1.0
document, written the way Postman's own "Export > Collection v2.1" writes one
(core/postman_export.hpp). It is the inverse of the Postman importer: a
collection imported from a Postman export and exported again gives back the
same document, _postman_id aside, and exporting, importing and exporting
again is byte-identical. Each item[] lists a collection's sub-folders and
requests in its one sibling order (#2535), so a request that sits
before or between folders is written there, which is where Postman runs it;
the Postman importer reads that order back.
Reads only. Nothing is stored. The whole subtree is exported, with no stop at a collection bound to another OpenAPI document.
Request:
{
"collectionId": "col_9a1f...", // Required, non-empty
"includeSecrets": false // Optional - default false
}
includeSecrets: false writes every credential as "": a bearer token, a
basic or digest or NTLM password, an API-key value, an OAuth 2.0 client secret
or password-grant password, an AWS key pair or session token, and the value of
a variable marked secret. The auth modes kept as a config bag (AWS, digest,
NTLM, Hawk, OAuth 1.0, EdgeGrid, JWT, OAuth 2.0's own config) are blanked by an
allowlist of the members known to describe the auth, not by credential name, so
a member no list has heard of (Insomnia's IAM secretAccessKey) leaves blank.
OAuth 2.0's extra request parameter rows, in its config and in a kept Postman
block alike, keep their keys; a row's value is blanked when its key names a
credential (client_secret, client_assertion, password, Authorization,
X-Api-Key, the other names a header or query parameter is blanked by).
A credential outside an auth block is blanked too, by name, wherever the
document writes a value as typed or as recorded:
- a request header whose name is sensitive (
Authorization,Proxy-Authorization,Cookie,Set-Cookie,X-Api-Key,X-Auth-Token,X-CSRF-Token, the other names the logger redacts) or is the header an API-key auth in force for the request names, enabled or not; the row and its name stay. The auth in force is the request's own, or the nearest folder's when it inherits; - a query parameter by the narrower name set of the Params table (the same
names less the generic
codeandkey, plussecret,signature,x-amz-signatureand the like, plus an API-key auth's own parameter), in the Params rows and in the URL'srawquery and fragment, and the password of the URL'suser:pass@(the user name stays); - on every saved example, the recorded request's headers and URL by the same
rules, the response's
header[]by the header names (aSet-Cookierow included, in full), and the value of everycookie[]entry whatever its name (the name, path, flags and expiry stay). An example written from the request's current state carries the request's own blanked rows.
A value that is exactly one {{variable}} reference names a secret without
being one and is kept. Each blanked value is counted in secretsOmitted; a
credential the document writes twice with one source - a query parameter in the
URL and in the Params table, an example's originalRequest copied from the
request - is counted once, while a Set-Cookie row and the cookie[] value
it sets, or a recorded Authorization header and the auth beside it, are
two written values and count twice. A body is never judged (a response
example's body, a request body outside the form-data file rule) and cookie
names are not either, so neither is blanked. true writes everything as
stored, which is what Postman's own export does, and is byte for byte what it
was before these rules.
Response:
{
"text": "{\n\t\"info\": {\n\t\t\"_postman_id\": \"9a1f...\",\n ...",
"fileName": "Pet Store.postman_collection.json",
"notes": {
"requestsExported": 12,
"foldersExported": 3,
"secretsOmitted": 2,
"notCarried": [
{ "code": "vayu_elements", "count": 4,
"message": "Assertions, extractors, timers, controllers, metrics and setup or teardown scripts have no Postman equivalent" }
]
}
}
textisJSON.stringify(document, null, "\t"): tab-indented, no trailing newline, keys in the order Postman writes them.info.schemaishttps://schema.getpostman.com/json/collection/v2.1.0/collection.json;info._postman_idis the collection id when that is a UUID, the UUID an engine id ends in (col_<uuid>), or else a version-8 UUID derived from the id. No_exporter_idor_collection_linkis written.fileNameis<collection name>.postman_collection.json, with every character a filesystem refuses (<>:"/\|?*and control characters) replaced by_.foldersExportedcounts the folders beneath the collection, not the collection itself.notCarriedhas one entry per kind of stored thing the format cannot carry, in a fixed code order, each with its count and a short phrase; an empty array means everything was carried.
| Code | Written when the collection holds |
|---|---|
vayu_elements |
An element other than a pre-request or post-response script (assertion, extractor, timer, controller, metric, setup or teardown script) |
script_settings |
A script with a name or the load-test inline setting |
jsonrpc_bodies |
A JSON-RPC body, written as a raw JSON body holding the completed frame (jsonrpc and id added as on send) |
unsupported_bodies |
A body in a mode Postman has no equivalent for, left out |
unsupported_auth |
An auth mode Postman has no equivalent for, left out |
oauth2_settings |
An OAuth 2.0 turned-off automatic token fetch or refresh, a token query parameter name, or an empty header prefix (an audience, resource and the extra request parameter lists are written as Postman's tokenRequestParams, authRequestParams and refreshRequestParams) |
form_file_names |
A form-data file part whose file name differs from its path's own |
body_file_details |
A binary body whose file states its own contentType, or a file name that differs from its path's own - Postman's file mode carries only src |
http_version |
A request's HTTP version other than auto |
event_stream |
A request consumed as an event stream |
request_timeout |
A request with a timeout of its own (Postman has only an app-wide one) |
mock_response_mode |
A mock response mode other than first |
truncated_examples |
An example saved from a cut-off response, written with the partial body |
example_content_types |
An example content type no Content-Type header row states |
variable_types |
A variable typed json, or a secret typed number, boolean or json, whose one type slot holds secret (number and boolean are otherwise written as Postman's own types); each row counted once |
data_contracts |
A collection or folder data-file contract |
spec_bindings |
A collection or folder bound to an OpenAPI document |
spec_operations |
A request stamped as an OpenAPI operation |
rows_without_key |
A header, param or form row with a value but no name, left out |
typed_auth_headers |
A request with an enabled header row named like the header its auth in force writes (Authorization for bearer, basic and an OAuth 2.0 token placed in the header; the key of an API key in a header), written with noauth - counted once per request |
An auth a Postman import kept its original block for (auth.postman, see
docs/engine/db-schema.md) is written as that block, while it still maps to
the stored auth; everything below describes the rest.
A header the user typed under the name the auth in force writes wins in Vayu
(apply_auth skips a name the request already carries, case-insensitively and
whatever its value), while postman-runtime lets the auth overwrite the header.
The request is therefore written with auth: {"type": "noauth"} (also over an
imported auth.postman block) and counted as typed_auth_headers, so the
header Postman sends is the one Vayu sends. Nothing is written for an auth that
writes no header (a blank bearer token, an API key with no name or placed in
the query, an OAuth 2.0 token placed in the query) or for a disabled row; a
folder's or collection's auth is left as it is.
What maps where: folders are item groups (a folder's sub-folders and requests
are written as one list in sibling order, a folder first on a tie); a request's inherit auth is an absent auth and its none is
noauth, while a collection's or folder's none is an absent auth and its
noauth is noauth; aws auth is awsv4; body modes json / text / xml
are raw with that options.raw.language (or the language a Postman import
kept as rawLanguage, none at all for "", while importing it again would still
give its stored mode), graphql is graphql with the
variables as the pane's text, x-www-form-urlencoded is urlencoded and
form-data is formdata with a file part's src and any part's contentType, binary is file with
file.src (file: {} when no file is chosen); url.query[] is every stored
query row in stored order (a turned-off one disabled: true), then the pairs
of the URL's own query that no enabled row states, in URL order, so a request
stored with its query only in url before the write kept the rows in step (see
POST /requests, issue #3551) keeps it - Postman and
Newman read query[] over raw, and a row matches a pair by key and value (as
the row is written into the URL), each row accounting for one pair so a repeated
key is not doubled; script.pre /
script.post are the prerequest / test events, one event per element in
element order, a turned-off one written disabled: true (Postman's runtime
skips it, as Vayu does); saved examples are
response entries with an originalRequest (see below).
protocolProfileBehavior. A request imported with one (its
postmanProtocolBehavior) is written as that object, member order, explicit
defaults and keys Vayu does not apply included, with each key Vayu owns checked
against the stored setting (issue #1765): strictSSL (verifySSL),
followRedirects, maxRedirects, disableUrlEncoding and disableCookies
keep the imported spelling while it reads as the stored value (absent or
not the right type reading as the default) and are otherwise overwritten in
place, or appended when absent; disabledSystemHeaders is kept while its
names set to true are the stored set, and otherwise written as
{name: true} in stored order; disableBodyPruning and every other key are
the imported object's. Without one, the object is generated in the order
strictSSL, followRedirects, maxRedirects, disableUrlEncoding, disableCookies,
disabledSystemHeaders, disableBodyPruning, each only where it differs from
Postman's default: strictSSL: false, followRedirects: false, a
maxRedirects other than 10, true for either flag, the non-empty header
list, and disableBodyPruning: true on a GET or HEAD that sends a body.
A folder or collection is never given one: an import flattens a folder's
protocolProfileBehavior onto the requests below it (#2538), so its applied
settings come back on those requests and a key Vayu does not apply is lost.
Saved examples. An example imported from Postman carries the saved
response it came from (request_examples.postman_response), and so does one
saved in the app from a live response (savedFrom on
POST /requests/:id/examples); either is written back
from it in the source's member order: originalRequest (the request as it was
recorded, not the request's current state), responseTime,
_postman_previewtype and any other member as stored; name, code and
body from the example's own fields. The status text is the stored one while
status is still the code it was recorded with, header[] (its name fields
and number values included) while headers still reads the same, cookie
while the enabled Set-Cookie rows (name in any case, and value) still read as
the recorded header[] has them (an edit to those rows rebuilds cookie from
them, a Max-Age counted from the export, so a removed row's value is not
exported; an unrelated header edit keeps it byte for byte), and the
preview language and type while the declared Content-Type is unchanged; an
edit to any of those regenerates the part it made stale. A member the source
left out (code, status) stays out until an edit gives it a value. The
recorded request's auth is written in v2.1's attribute-array shape (a v2.0
file states it as an object, which the v2.1 schema refuses), and with
includeSecrets: false it is blanked like any other credential and counted in
secretsOmitted, as are the credentials in the recorded request's headers and
URL, the response's Set-Cookie and other sensitive header[] rows and the
values in cookie[]. An example with no stored response
(saved in Vayu before #1763 or from a response restored from a stored run, or
imported from OpenAPI) gets originalRequest from the
request's current state, the status text from the engine's reason-phrase table
and _postman_previewlanguage from its Content-Type (Text when it states
none), with cookie: [].
Errors:
- 400 Invalid body: must be an object.
- 400 Invalid 'collectionId': must be a non-empty string.
- 400 Invalid 'includeSecrets': must be true or false.
- 404 Collection not found.
POST /export/postman-environment¶
One environment as a Postman environment export (core/postman_export.hpp), the
inverse of the Postman environment importer: importing the document gives back
the same variable names, values, enabled flags, secret flags and types, apart
from json (below). Reads only.
Request:
{
"environmentId": "env_9a1f...", // Required, non-empty
"includeSecrets": false // Optional - default false
}
includeSecrets: false writes the string value of every variable marked secret
as "", counted in secretsOmitted; the row stays, still typed secret, so the
name is visible for the person importing it to fill in. A secret whose value is
exactly one {{variable}} reference names a secret without being one and is
kept, uncounted. true writes every value as stored.
Response:
{
"text": "{\n\t\"id\": \"env_9a1f...\",\n\t\"name\": \"Production\",\n ...",
"fileName": "Production.postman_environment.json",
"notes": {
"variablesExported": 6,
"secretsOmitted": 1,
"notCarried": [
{ "code": "variable_types", "count": 2,
"message": "JSON variable types have no Postman equivalent, and typed secrets were written as secret" }
]
}
}
textisJSON.stringify(document, null, "\t"): tab-indented, no trailing newline. The document is{id, name, values, _postman_variable_scope: "environment"}:idis the environment's id,valuesholds one{key, value, type, enabled}row per variable in the stored order, and no export timestamp is written. A row has nodescription.- A row's
valueis the stored value as the text a send uses (#3245): a string verbatim, a number or boolean as its JSON text (5is"5",trueis"true"), an object or array as compact JSON ({"a":1}), an absent ornullvalue"". Itstypeissecretfor a secret variable, else the storedstring,numberorboolean, elsedefault, Postman's unset marker.enabledis the stored flag,truewhen absent. fileNameis<environment name>.postman_environment.json, with every character a filesystem refuses replaced by_(environmentwhen nothing is left of the name).variablesExportedcounts the rows written. A stored variables column that does not parse as an object exports as no variables.notCarriedholds onevariable_typesentry for the types a row could not carry: a variable typedjson, which Postman has no type for, is written asdefault, and a secret typednumber,booleanorjsonis written assecret, Postman's row having onetypeslot (#3252). The entry'scountis how many rows, each counted once. No entry means every type was carried. A storedcreatedAtis not written; Postman's row has no place for it.
Errors:
- 400 Invalid body: must be an object.
- 400 Invalid 'environmentId': must be a non-empty string.
- 400 Invalid 'includeSecrets': must be true or false.
- 404 Environment not found.
POST /export/run-report¶
A finished load run as a document to share (issue #2127): its report, the
configuration it ran with and its time series, with everything that could carry
a credential or a payload left out (core/run_export.hpp). The document's
schema is run-export.schema.json, JSON Schema
draft-07 with additionalProperties: false at every level. Reads only.
Request:
{
"runId": "run_5a7c...", // Required, non-empty
"format": "json", // Optional - "json" (default), "markdown", "html"
"series": "full", // Optional - "full" (default) or "none"
"baseRunId": "run_e8f0..." // Optional - a second finished load run
}
json, markdown and html are written. The formats are one table
(RUN_EXPORT_FORMATS), so each adds a row and its renderer, and a row to
engine/tests/fixtures/run-export-formats.json, which the app's format
registry and the MCP server's list are held to. Every format renders the same
document, so what the rules below leave out is left out of all of them.
series: "none" leaves timeSeries out; full reads every tick of
GET /runs/:runId/metrics, paged at its 50000-tick
maximum to the end. html draws the series, so it reads every tick whatever
series says. baseRunId is checked like runId (below) and fills the
document's comparison; without it comparison is null.
Response:
{
"text": "{\n \"schema\": \"vayu.run-report\",\n \"schemaVersion\": 1, ...",
"fileName": "Create order 2026-10-05 0810.run.json",
"mimeType": "application/json",
"notes": { "urlCredentialsOmitted": 1 }
}
textis the document: forjsontwo-space indented with invalid UTF-8 replaced, formarkdownthe report below, forhtmlthe page below.mimeTypeisapplication/json,text/markdownformarkdownortext/htmlforhtml.fileNameis<title> <UTC start, YYYY-MM-DD HHmm>.run.json(.run.mdformarkdown,.run.htmlforhtml), with every character a filesystem refuses replaced by_(the rulePOST /export/postmanuses;runwhen nothing is left). The title is the one the run's reference line uses (below).notes.urlCredentialsOmittedcounts the values the URL rule below dropped.
What the document carries is an allowlist. Every member is copied from the report or the run's stored snapshot by name, so a field the report gains later is absent here until it is added on purpose:
- No
results[], no trace (trace,rawRequest,sentHeaders), no captured sample, anywhere. A trace records what was sent, credentials included, and a sample holds response headers and bodies verbatim. configholds themethod; theurlafterredact_url_credentials(core/vayu_extensions.hpp: auser:pass@password dropped and the user name kept, a credential-named query or fragment value emptied, a lone{{variable}}kept);headerNamesandparamNames, names only, whether enabled or not;bodyas{mode, bytes},bytesthe size of the body text as stored andnullfor a body that is not text;authas{mode}; and the report'smetadata.configurationtuning object. Never a header or parameter value, never the body.- Text the engine copied from a script or a response is carried as counts
only:
schemaValidationkeepsfailuresTotaland dropsfailures[], alifecycleoutcome drops itsmessage,messages,consoleand their dropped counts, an element row (a step's or the run'selements) dropsmessages,consoleand their dropped counts (#3127), and the report'sauthsection (whoselastErroris a token endpoint's words) is left out. - Text the user wrote (the request name, the run comment, the data file's display name, step, transaction, metric and series names) is carried as written.
- Within a section a value is copied only when it is a scalar or a list of scalars; anything deeper is named member by member.
The document ("schema": "vayu.run-report", "schemaVersion": 1; a
breaking change bumps the integer and is noted here):
| Member | Holds |
|---|---|
generatedAt, engineVersion |
Epoch milliseconds of the export; the engine's version |
run |
id, reference, type (load), status, startTime, endTime, name (the request name, or null), comment (or null), baseline |
verdict |
{state, stoppedEarly, reason}, derived below |
config |
As in rule 2 |
report |
summary, latency, statusCodes, errors, and when the run has them rateControl, timingBreakdown, stream, slowRequests, sampling, warnings, scenario (step and transaction aggregates, and a scenario load run's exact assertions), monitor, testValidation, capacity, coverage, schemaValidation (counts), lifecycle (outcomes), elements, thresholdValidation, assertions (the run's assertion block, #3537), customMetrics - each as GET /runs/:runId/report documents it, less what the rules above leave out |
timeSeries |
One entry per tick: elapsed_seconds, requests_completed, requests_failed, current_rps, current_concurrency, throughput, error_rate, status_codes, status_seconds, latency_p50_ms, latency_p95_ms, latency_p99_ms (the tick's own second, as stored: the three percentiles are absent from a second with no completion, issue #2386, and the HTML charts skip that point rather than drawing 0 ms; status_seconds is as stored with any entry that is not {second >= 0, span >= 1, counts} of five counts >= 0 dropped, an empty list kept, and the key absent from a tick stored before issue #2866); absent for series: "none" |
comparison |
null without baseRunId; otherwise {baseRunId, baseReference, differences, deltas, statusCodes}, below |
notCarried |
[{code, message}], one entry per kind of thing this run held that the document left out, in the order traces_and_samples, request_values, message_text, credential_refreshes |
statusCodes, errors.byStatusCode and a tick's status_codes are objects,
code to count, in the document: the report itself writes the first two as
[[code, count], ...] pairs.
run.reference is the Copy for agent run line
(MCP: Naming what the user means) with the
start in ISO-8601 UTC, because a file is read away from the locale and zone the
app would print it in: Vayu run "Create order" (run_5a7c...) - load test, POST
/v1/orders, 2026-10-05T08:10:00Z, completed. The title is the request name
unless it is the default New Request, else the collection a collection load
run ran, else the method and path; the URL is cut to its path.
verdict reads the report fields the app's run verdict reads (judgeRun in
app/src/components/shared/run-outcome.ts): status, summary.totalRequests
and summary.errorRate, summary.drainCut, thresholdValidation, and the
report's top-level assertions block, for a
single-request run and a scenario load run alike (#3537). A failed check is a failed assertion of
either population (exact.failed or sampled.failed), an errored element
execution (errored) or a failed teardown (teardownFailed); like an errored
request, it keeps met budgets from reading passed without failing a run that
declared no budget for it. The first matching row wins:
status and budgets |
state |
reason |
|---|---|---|
stopped |
not_judged |
stopped |
failed, no budget missed |
failed |
run_failed |
A declared budget missed (thresholdValidation.failed > 0) |
failed |
budgets_missed |
A Stop cut the run's own drain (summary.drainCut.cancelled > 0; #3538) |
not_judged |
drain_stopped |
| No budget declared | not_judged |
no_budgets |
Every budget met, some requests errored (summary.errorRate > 0) |
not_judged |
budgets_met_with_errors |
Every budget met, an assertion failed (assertions.exact.failed or assertions.sampled.failed > 0; #2820, #3458) |
not_judged |
budgets_met_with_assertion_failures |
Every budget met, an element execution errored (assertions.errored > 0) |
not_judged |
budgets_met_with_element_errors |
Every budget met, a teardown failed (assertions.teardownFailed > 0) |
not_judged |
budgets_met_with_teardown_failures |
| Every budget met, none of the above | passed |
budgets_met |
reason names the first failed check; the Markdown and HTML line names every
one (below). A cut drain removed the run's slowest requests from every figure,
so what is left is not judged however well it did: its line is 15 requests
were still unanswered when the drain was stopped, and a budget the answered
requests already missed still fails the run. A report with no assertions block (a run that asserted nothing
and errored nowhere, or one stored before the block whose old fields derive
none) has no failed check. engine/tests/fixtures/run-verdict-conformance.json
pins this table to the app's: the engine's suite replays it through the export
and the app's through reportOutcome.
stoppedEarly is status == "stopped".
A summary that is not a whole-run measurement (issues #2895, #2905).
report.summary carries two optional booleans, each present only when true
(the GET /runs/:runId/report flags of the same name): partial for a run the
engine died under and reconciled at the next start, whose counts are its last
saved tick's, and summaryMissing for a failed load run that stored no summary,
whose counts are not whole-run totals. In both, report.latency is absent
(the schema no longer requires it, #2938): a crashed run flushed no rows to
take a percentile from, and the sampled rows of a failed run with no summary
are not the run's latency. The Markdown and HTML latency table then reads -
in every row.
The verdict is not changed by either; the Markdown and HTML reports word it
(below).
comparison diffs the run (the target) against baseRunId the way the app's
vs-baseline strip and the MCP compare_runs tool do (compareReports): the
engine's copy is core/run_compare.hpp, and
engine/tests/fixtures/run-compare-conformance.json pins all three to the same
answers. Its members:
baseRunId, andbaseReference, the base run's line written asrun.referenceis.differences[]:{field, base, target}for every way the two runs were not the same experiment, in the orderrun_type(Send,Load testorCollection run; the export takes load runs only, so it does not arise here today),mode,concurrency(virtual users; for a ramp the start level and ramp time too),target_rps,duration(only past a 2x ratio; an unfinished run's status is appended,"3 s, stopped"),status,http_version(autodiffers from nothing),data_file(name and the first 8 characters of its hash, then, numbers read as numberswhendataFileCastNumbersis set; none against one is a difference, and so is one file read both ways, #2540, since the hash is of the bytes),request(method and URL with the query, fragment and userinfo cut),compressionandexpect_continue(#2516;allowedagainstnot allowed, an absent key reading asnot allowed). The two values are strings formatted as the app shows them. Every report the export reads carriesmetadata.runType, so amode,concurrencyortarget_rpsonly one run recorded is listed, its missing sidenot recorded(the shared rule leaves such a field unknown when either report lacksrunType); any other field only one report carries is unknown and not listed. Read these before the deltas: a short stopped run against a long one always looks like a regression.deltas[]:{metric, base, target, delta, pctChange, direction}, one per metric in this order:
metric |
direction |
|---|---|
latency.p50, latency.p90, latency.p95, latency.p99, latency.avg, latency.max |
lower-is-better |
summary.avgRps, summary.throughput |
higher-is-better |
summary.errorRate |
lower-is-better |
summary.totalRequests |
neutral - it moves with how long a run was told to run |
delta is target - base and pctChange is delta / base * 100. A value a
report lacks is null, and so is every figure computed from it; pctChange
is null against a zero base. So is a figure the report says the engine did
not record (#2904), judged per run: summary.summaryMissing (a failed run
with no summary) nulls that run's summary.* metrics and its latency, and
summary.partial (reconciled after a crash) nulls its latency alone, so the
other run's value stands and the delta is null. The base's own headline
numbers are the entries' base values.
- statusCodes: {code: {base, target}} over every code either run saw, a
code one run never saw counting 0.
The Markdown report¶
format: "markdown" renders the document above as plain GitHub-flavoured
Markdown, to paste into a pull request or an issue, or to save as
<title> <UTC start>.run.md (core/run_export_markdown.hpp). It is a pure
function of the document: it reads no database and no report, so it can say
nothing the document does not. No raw HTML and no images. Its size does not
grow with the run: the time series is never read, and a table fed by an open
set (status codes, error types, warnings) shows ten rows and folds the rest
into one Other (<n> codes) row, so a 2-hour run that saw 300 status codes is
still under 6 KB. The tables a plan or a spec feeds (steps, transactions and
the contract's operations) show twenty rows in document order, the order of the
plan and never sorted by count, and fold the rest into one and <n> more steps
row.
The sections, in order:
# <title>, then the run's reference line in a code span (the same linerun.referenceholds).- The verdict, from the document's
verdictand never recomputed:**Passed** - 3 of 3 budgets met,**Failed** - p95 <= 30 ms missed (41 ms)(every missed budget, ornot evaluatedfor one the run could not measure),**Not judged** - no budgets declared. Met budgets that did not pass, and no budgets, name every failed check ofreport.assertionsin this order, after the error rate when requests errored:150 assertions failed,4 assertions failed in the sampled replayor150 assertions failed, 4 more in the sampled replay;3 elements errored;1 teardown script failed(**Not judged** - 3 of 3 budgets met, but 0.4% of requests errored, 68 assertions failed,**Not judged** - no budgets declared; 91 assertions failed in the sampled replay, #3537). A cut drain is its count alone:**Not judged** - 15 requests were still unanswered when the drain was stopped(1 request was, #3538). For a stopped run a lineStopped early at 3 s of 20 sfollows, and for a run withsummary.partialorsummary.summaryMissingone sentence each follows that, saying the totals are the last saved tick's or not whole-run totals, and that latency was not recorded (the latency table then reads-in every row, #2938). ## Run: target (<METHOD> <url>, orCollection run, 3 steps per iteration- the step count isreport.scenario.steps, left off when the document holds no per-step stats), mode, virtual users, duration, start (ISO-8601 UTC), engine version and the comment. Acapacityrun reads its configuration as a search:Search from 1 up to 128 virtual users(the first level and the ceiling),Deadline 300 s, ran 62.4 s(the configured deadline, thensummary.testDuration, because the search ends when it finds its limit) and aSteprow withconfiguration.stepDurationas it was sent (5s, or a number of seconds).## Results: requests, aSkipped requestsrow only whensummary.skippedRequestsis above 0 (625 requests skipped: the load generator stalled for 2.5 s, fromskippedRequestsandstalledMs, issue #2911; absent or0prints no row), requests per second (avgRps, labelled as the whole run with the drain included), responses per second while sending (completedWhileSending / sendingDurationSeconds, issue #2882, only when the report has both), error rate with its split into HTTP errors and no response, bytes in and out, and the throughput and error-rate budgets that judged them. The error rate is the report's, never derived from the counts.## Latency: min, p50, p90, p95, p99, p999 and max, with the budget that judged each (<= 30 ms - missed). A scenario run's table opens with the line*All steps pooled.*: it is one histogram over every step, and the per-step figures are the Sequence table's. A streaming run's table opens with*Each stream's full duration.*(after that line, for a run that is both).## Stream, only for a run whose document hasreport.stream, which a streaming run carries and every other run lacks (#3240). A line saying what the Latency table above is (The Latency table above is each stream's full duration, not the time to its first event.: a stream's latency is its whole transfer, so it grows with the events the server sends), then a table ofStreams(completions),Events(totalEvents),Events per second(eventsPerSecond, inevents/s) andStreams ended at a cap(capped), then a table with a p50, p95, p99 and max row of the events each stream delivered (events, whole counts) and, as aTime to first event (ms)column, of the time to each stream's first event (timeToFirstEvent). That column is left off when the document has notimeToFirstEvent, which the engine omits when no stream delivered a timed event, so a zero never stands for a figure that was not measured. A figure the document lacks reads-.## Capacity, only for a run whose document hasreport.capacity: the stop reason in bold and what the search found (`Latency budget exceeded- Sustained 41 virtual users at 403 req/s, with a p99 of 178 ms against a
200 ms budget.
), then where the limit sits (The limit lies between 41 and 51 virtual users: it held 41 and gave out at 51, where p99 reached 226 ms.), why it stopped in the document's own figures (p99 stayed above the budget across two consecutive measurements of the level (each 5s long).), the budget, error limit and step length the search ran under, and a table of the levels it judged: virtual users, throughput, p99, plusErrors (%)andSamplesonly when some level carries them (a run stored before the engine reported them has neither). A level the search measured twice reads51 (re-measured), and a p99 or error share past its limit says(over budget)or(over limit)in words. The sentences are the app's Capacity summary's (components/shared/CapacitySummary.tsx, with the stop reasons' labels and detail lines incomponents/shared/capacityStop.ts): the stop-reason table inrun_export_view.cppandcapacityStop.tsword the same stops, so a change to one is a change to both. A reason neither table knows (a newer engine's) prints under its raw key with no detail line. What the search found depends on why it stopped: a measured capacity when the target gave out (slo_exceeded,errors_exceeded),At least N virtual users held the budgetwhen it ran out of ceiling, time or patience (cap_reached,deadline,stopped), the saturation level when throughput plateaued, andThe search ended before it finished measuring a single levelwhenlevelsis empty. A latency here is spelled178 msas the rest of this report spells it, not178ms` as the app does. ## Contract, only when the document hasreport.coverageorreport.schemaValidation, which a run of a collection bound to an OpenAPI document carries and every other run lacks (#3036). Up to three lines, each present when its section is:Coverage: 3 of 5 operations covered; declared-response coverage 80.0% (8 of 10).(the percentage is the document'sdeclaredResponseCoveragePct, never recomputed from the counts);Schema validation (sampled): 100 responses sampled, 90 checked (87 valid, 3 failed), 10 unchecked., which sayssampledunless the section hasexact: true(a collection run, which checked every step:Schema validation (every step checked): 100 responses, ...), because a load run's check walks a reservoir; andUnchecked: body is not JSON or nests too deeply (6), no schema for the status (4)., the three commonestuncheckedReasonswith the rest counted (and 2 more reasons), worded as the app'sresponse-viewer/validation-reasons.tswords them, shorter, and a code it does not know under its raw key. A table follows with a row percoverage.operations[]entry in document order (method and path, operation id, requests sent, declared responses hit and missed), folded past twenty rows intoand <n> more operations. The path and operation id are the spec author's text, escaped as every name is.## Sequence, only for a scenario run whose document counts iterations or lists steps: one line (2,110 iterations started, 2,090 completed, 15 abandoned, 5 cut short- abandoned and cut short only when above zero, cut short being started less completed less abandoned, as the app derives it), then a table with a row per step in plan order: executed, errors,Assertions(2,080 passed, 18 failed, summed from the step'sassert.*andscript.*element tallies, anerrorcounted as failed, with each miss of arequiredextractor added to the failed count because it failed the step;deferred to a post-run replayfor a script the engine only replays afterwards;-for a step that asserts nothing) and its p50, p95 and p99. Step names are free text and escaped as every name is.## Transactions, only when the run declared any: name, count, errors and p50, p95 and p99 perreport.scenario.transactions[]entry.## Errors, only when there were any: by status code (HTTP 503), then by transport error type. A request that got no response is listed once, under its error type: status code 0 counts the same requests, so no row readsHTTP 0(issue #2400). ANo responserow (the app's words) appears only when the error types sum to less than code 0, which is a run stored before the per-type counts, whose types stop at the error store's cap; its count is the remainder (code 0 minus the types' sum), so the requests no type names are not lost and none is listed twice. With no error types at all it holds the whole of code 0. The HTML report reads the same table.## Compared with <base reference>, only when the document has acomparison: each metric's base, this run, change and a word from the delta's owndirection(improved,regressed,unchangedfor a change of exactly zero,-for a neutral metric that moved, such as the request count, which is neither better nor worse, ornot comparedfor a figure one run lacks), then one line percomparison.differences[]entry.## Warningsfromreport.warnings, and the footerGenerated by Vayu <version>. No request or response data is included.A warning'snamesare appended as: a, b, c(the first five, thenand N more) unless itsmessagealready ends with:and every name joined by,, which is how the engine writes an unresolved-variable warning, so each name appears once.
Every table is padded to its widest cell so it reads as a table before it is
rendered. All free text (the title, URL, comment, error types, warning text)
goes through one escape_markdown_cell: line breaks and control characters
become a space, and \, `, |, <, >, [, ], *, ~, an &
that would write an entity, an _ that is not inside a word and a leading block
marker (#, -, +, 1.) are backslash-escaped, so a request named
a | b <script> cannot split a table or start a tag. Numbers are spelled
the same on every host, whatever its locale: , groups thousands and .
marks decimals. A latency or rate has two decimals below 10 (trailing zeros
dropped) and none from 10, <0.01 for a positive value that would round to 0;
a percentage has one decimal and <0.1 likewise. The tiers are pinned by
engine/tests/fixtures/run-export-number-tiers.json.
engine/tests/fixtures/run-export/<case>.document.json and <case>.golden.md
hold the renderer to its exact bytes for each shape of run
(run_export_markdown_test.cpp); a deliberate change to the output is
regenerated with VAYU_UPDATE_GOLDEN=1, never edited by hand.
The HTML report¶
format: "html" renders the same document as one self-contained page, to open
in a browser, attach to a ticket or print: <title> <UTC start>.run.html
(core/run_export_html.hpp). Like the Markdown report it is a pure function of
the document, so it can say nothing the document does not.
It holds the Markdown report's sections in the same order (title and reference
line, verdict, run, results, latency with its budgets, a streaming run's
events, a capacity search's result, the contract's coverage and schema checks,
a scenario's sequence and transactions, errors, comparison, warnings),
written as semantic HTML - one h1, tables with th scope, a description list
for the run - from the same reading of the document, so the two cannot word a
verdict or a capacity result differently. Stream (#3240), Capacity, Sequence and
Transactions (#2819) are sections of paragraphs and tables like the rest, each
present only when the document has it: the Stream section is the Latency note
above its totals and distribution tables, the capacity sentences are paragraphs above the levels
table, the iteration line is the paragraph above the steps table, the Contract
section (#3036) writes its coverage, validation and unchecked-reason lines as
paragraphs above its operations table, and a level or
assertion count past its limit carries the same word beside its colour ((over
budget), 18 failed). A table's one-line caption (a scenario run's latency
table, All steps pooled.) is its <caption>; the partial and missing-summary
sentences sit in the verdict's band, one paragraph each. Above the title sits a one-line brand
(the Vayu mark at 28 px, then the wordmark Vayu run report, muted; the mark has
an empty alt because the wordmark names the product). The mark is
shared/icon_png/vayu_icon_64x64.png, embedded as a base64 data: URI
(run_export_html_logo.hpp) because it exists only as a raster; the test suite
compares the embedded bytes with that file. Then come three charts drawn from
timeSeries, then the footer, which names the engine version:
- Throughput (req/s) and virtual users, two stacked panels sharing the x-axis.
- Latency p50, p95 and p99 in ms, with the p95 budget as a labelled dashed line when the run declared one. The axis stretches to reach the budget, so a generous budget is drawn however far above the data it lies.
- Responses by class: 2xx/3xx, 4xx, 5xx and No response (status code 0). A
class that saw no response is not drawn and has no label. The chart reads the
series one of two ways, chosen once for the whole
timeSeries: - When any tick carries
status_seconds(issue #2888, runs stored after #2866), it is responses per second: one point per entry atcounts[i] / span, at the end of the entry's span (second + span), the entries kept once persecond(the last wins) and in second order, with 3xx counted into 2xx/3xx. The ticks' own timing moves nothing, and a tick without the key adds no point. A series whose everystatus_secondsis empty draws no status chart. - Otherwise (a run stored before #2866) it is responses per tick: a tick carries cumulative counts, so each class is drawn as what it gained since the previous tick, a count that moved backwards adding nothing.
Every y-axis starts at 0 and names its unit, the x-axis is seconds from the start
of the run, and each line is labelled where it ends instead of in a legend; the
percentile lines differ in lightness, not hue, since red and amber mean failure
here. Each chart has an accessible name and a <desc> giving every series'
minimum, maximum and the time of its peak, read from every tick. A line is
drawn from at most 480 points: a longer series is cut into 240 stretches and
each keeps its lowest and highest value, so a one-tick spike survives, and the
file stays under 300 KB for a run of any length.
The page loads nothing and runs nothing. There is no script, no <link>,
frame or font and no url(...); the one image is the brand mark above, an inline
data:image/png URI, so it is the only src attribute and it cannot fetch
anything. A Content-Security-Policy meta tag (default-src 'none'; style-src
'unsafe-inline'; img-src data:) enforces that: no request leaves the page. The
only href values are # anchors to the
page's own sections: the target URL is text, never a link. The charts are inline
<svg>, which is why hovering a line shows its summary natively. Every string
written into the page (name, comment, URL, error keys, warning text, data file
name) goes through one escape_html, in text and attribute position alike.
The page follows the reader's colour scheme (color-scheme: light dark, the
palette switched by prefers-color-scheme, no toggle) and prints light on A4
(@page margin 14 mm, sections and charts kept whole, the verdict band printed
in colour). Pass and fail are always a word beside the colour (Passed,
Failed, Not judged, met, missed); the palette holds 4.5:1 for text and
3:1 for graphics in both schemes (run_export_html_test.cpp measures it).
engine/tests/fixtures/run-export/<case>.golden.html pins the bytes for nine
shapes of run, among them a capacity search, a scenario run and two streaming
runs, regenerated like the Markdown goldens.
Errors:
| Status | error.code |
When |
|---|---|---|
400 |
bad_request |
The body is not an object; runId missing or empty; format not one of the table's names; series not full or none; baseRunId not a non-empty string, or equal to runId |
400 |
unsupported_run_type |
The run or the base is a design or collection-sequence run |
404 |
not_found |
The run or the base does not exist |
409 |
run_in_progress |
The run or the base is pending or running: its numbers are not a result yet. A stopped run is a result |
Environments¶
GET /environments¶
List every environment, except those in the trash (#2970).
Response:
[
{
"id": "env_1234567890",
"name": "Production",
"variables": {
"baseUrl": {
"value": "https://api.example.com",
"enabled": true,
"secret": false
}
},
"updatedAt": 1234567890
}
]
POST /environments¶
Create an environment. Create only - see Resource writes for the shared contract and the null-vs-absent rule.
Request:
{
"name": "Production", // Required, no default (null is a 400)
"description": "", // Optional
"isActive": false, // Optional; true deactivates every other environment
"variables": { // Optional, null resets to {}
"baseUrl": {
"value": "https://api.example.com",
"enabled": true,
"secret": false
}
}
}
Response: The created environment object, carrying the engine-generated id.
Errors: 400 if the body carries an id
(the engine owns it), if name is missing or
null, if name is empty or whitespace-only (#3253), or if a
variables key is blank or padded
(#3251); 413 naming the field, its size and the cap,
when a serialized variables is over the engine's
field cap.
A storage failure answers 507, 503 or 500, never 400 - see
A storage failure is not a 400.
PUT /environments/:id¶
Update an existing environment. Update only - a 404 when the id does not
exist, never a silent create. Merge-patch body, same rule as collections.
variables replaces the whole map, so a caller doing a partial edit reads the
current map first and sends the merged result under the version it read,
If-Match: W/"<updatedAt>" (this is what the MCP update_environment tool
does; see Conditional updates). Sending
variables: null resets it to {} -
it no longer stores the literal string null, which is the bug this verb split
fixed. isActive is honored here too; it used to be read only on create.
Writing isActive: true is how a client switches the active environment, and
one request does the whole switch: the engine deactivates whichever environment
held the flag in the same transaction, so at most one row is ever active and a
client sends no companion write to clear the old one. Clearing entirely is
isActive: false on the environment that holds it. The engine still never
applies the active environment to a request - every execution names its own
environmentId - but because the choice is stored rather than kept client-side,
it survives a restart and is shared by every client on the same database. See
db-schema.md.
Request:
{
"name": "Production", // Optional; null is a 400 (no default)
"variables": {}, // Optional, null resets to {}
"isActive": true // Optional, null resets to false; true is the switch
}
Headers: If-Match (optional), see
Conditional updates.
Response: The updated environment object, with its ETag.
Errors: 404 if the environment does not exist; 412 if If-Match no
longer names the stored row; 400 on a null or empty or whitespace-only
name (#3253), a malformed If-Match or a blank or padded
variables key (#3251);
413 naming the field, its size and the cap, when a serialized variables is
over the engine's field cap.
A storage failure answers 507, 503 or 500, never 400 - see
A storage failure is not a 400.
DELETE /environments/:id¶
Delete an environment. The delete is soft (#2970): the row is stamped
deleted_at, its isActive is cleared in the same write, and
GET /trash lists it until a purge. From then on every route here
treats the id as missing - GET /environments leaves it out, PUT and a second
DELETE are a 404, POST /export/postman-environment is a 404, and an
environmentId naming it composes and sends as an id naming nothing: an empty
scope, so its {{names}} stay unresolved.
Restore it with POST /trash/:id/restore, which brings
it back inactive; destroy it for good with DELETE /trash/:id,
which is also what the startup sweep does once trashRetentionDays has passed.
Its cookie jar is kept while it is in the trash, out of
GET /cookies, so a restore brings its session back; a purge drops it.
Response:
Errors: 404 if no live environment has that id, a trashed one included.
A storage failure answers 507, 503 or 500 - see
A storage failure is not a 400.
Global Variables¶
GET /globals¶
Get global variables (singleton). An engine that never saved any answers the
empty set at updatedAt: 0. The row is created by the first POST /globals,
the first import carrying globals, or the first script or extractor write to a
global (pm.globals.set, an extract.* element with scope: globals): a
POST /execute or collection run on a workspace with no globals stores what its
scripts set rather than discarding it.
Response:
{
"id": "globals",
"variables": {
"apiKey": {
"value": "xxx",
"enabled": true,
"secret": false
}
},
"updatedAt": 1234567890
}
The answer carries the row's ETag, W/"<updatedAt>" (W/"0" for the
never-written row), which a later POST /globals may name in If-Match.
POST /globals¶
Set global variables.
Request:
Headers: If-Match (optional), see
Conditional updates.
Response: The saved globals object, with its ETag.
Errors: 412 if If-Match no longer names the stored row (the stored
updatedAt rides inside the error); 400 on a malformed If-Match, a
non-object variables or a blank or padded variables key
(#3251). None writes anything.
Globals is a singleton, so there is no create/update pair: a POST replaces
the whole set rather than merging into it. Every write is therefore a create as
far as the null-vs-absent rule goes - variables
absent and variables: null both mean the default, {}. A caller that keeps
the globals it did not name reads first, merges, and saves under the version it
read with If-Match: W/"<updatedAt>" (this is what the MCP update_globals
tool does). The engine judges the tag in the same lock acquisition as the
write, so a save that landed after the caller's read turns its write into a
412 rather than a silent loss.
variables: null used to store the literal four-character text null, which
parses as JSON but is not an object. GET /globals returns {} for anything it
cannot read as an object, so the failure showed up as globals silently
disappearing rather than as an error. A non-object variables (42, a string,
an array) had the same effect and is now a 400 - see
Accepted field shapes.
Change feed¶
POST /changes/subscriptions¶
Issues the id one GET /changes stream opens with.
The id is 32 random bytes from libsodium, single-use: the first GET
/changes that presents it spends it, whether that stream is then refused for
a full feed or served, and a second GET with it is a 403. A client asks for
a new one before every connection, a reconnect included. At most 64 issued ids
wait unspent (change_feed::MAX_PENDING_SUBSCRIPTIONS); asking for more drops
the oldest. This is a POST so a web page cannot send it: a page's request
carries an Origin, which the gate refuses, so a page
can neither learn an id nor open a stream.
GET /changes¶
GET /changes?subscription=<id>: Server-Sent Events, one change event per committed write of a collection, a
request, an example, an environment, the globals or a trash entry, whoever made
it: the app, the MCP server (in-app or stdio), vayu-cli or a script against
this API (#3420). A client that caches those rows subscribes once and refetches
what an event names, instead of polling or trusting a cache forever.
event: ready
id: 1789000000000000
data: {"lastEventId":1789000000000000}
event: change
id: 1789000000000001
data: {"kind":"request","id":"req_1","op":"update","collectionId":"col_1"}
event: change
id: 1789000000000002
data: {"kind":"example","id":"exa_1","op":"delete","requestId":"req_1"}
data of a change:
| Field | Meaning |
|---|---|
kind |
collection, request, example, environment, globals, or clientCertificate, the last only for what changes the trash (its delete, restore and purge; a certificate's create and update are not on the feed) |
id |
The row's id; globals for the globals singleton |
op |
create, update, delete (gone from every live read: moved to the trash, or an imported example kept as a tombstone), restore (back from the trash) or purge (destroyed for good: from the trash, by retention, or a spec sync's hard delete of a live request) |
collectionId |
The collection the row sits in: a request's collection, a sub-folder's parent. Absent for a root collection and every other kind |
requestId |
An example's request. Absent for every other kind |
What one write publishes. One event per row the write committed, after its
transaction commits, so a write that rolled back publishes nothing. A bulk write
(POST /import/apply, POST /reorder, POST /specs/sync, POST /specs/bind)
publishes one per row it wrote, in write order and with consecutive ids; a row a
sync names for deletion that is already gone publishes nothing. A cascade is
one event on the row the caller named: deleting, restoring or purging a
collection publishes one collection event for it, and the sub-folders,
requests and examples that went or came with it (a purge's re-parenting of a
live sub-folder included) ride on it, so a client refetches the tree. A save
that makes an environment active publishes for that environment only; the ones
it deactivated are read off the same list. A trash restore or purge names the
entry's own kind. A delete that finds nothing live publishes nothing.
Ids. id: increases by one per event. The first id of a process is its
start time in microseconds plus one, so an id kept from an earlier engine
process is below every id this one issues, and its resume is a reset rather
than a replay of the wrong process's events. An id stays below 2^53, exact as a
JavaScript number.
Every stream opens with one ready or reset, whose id: and
lastEventId say where the stream stands: ready at the newest id on a fresh
subscription, so an EventSource that drops before its first change still
resumes from it; ready at the resume point on a resume the feed still covers,
followed by every change after it; reset otherwise. Subscribe before the first
read of the data the feed describes, so no write falls between the two.
Resume with Last-Event-ID (what EventSource sends on its own retry) or
?lastEventId=<id> (for a client reconnecting by hand); the header wins when
both are given. A value that is not a non-negative integer is a 400 with code
invalid_last_event_id, the inbox stream's rule.
reset: refetch everything. The engine keeps the last 1024 events
(change_feed::MAX_RETAINED_EVENTS). A resume from an id older than that, or
from one this process never issued, opens with event: reset, and a connected
reader that falls a whole ring behind between two polls (an import larger than
the ring) is sent one mid-stream. The stream then continues from the reset's
id. Treat it as "every cached row may be stale".
A stream needs a subscription. subscription is the id
POST /changes/subscriptions issued. Without it
the answer is a 400 with code subscription_required; an id that was never
issued, was dropped or is already spent is a 403 with code
unknown_subscription. Neither holds a reader slot. A scriptless GET is all
a web page can send without an Origin, so a page can neither read the feed nor
fill its slots to lock the app out.
Several readers, a bounded number. There is no single-reader claim: every
stream reads the same feed. Each one parks a pool thread, so at most 8 are open
at once (change_feed::MAX_READERS); another is a 503 with code
change_feed_full and Retry-After: 15, the keep-alive interval within which a
closed stream's slot is noticed and freed. The id of a refused stream is spent:
ask for another.
A stream writes : keep-alive after 15 quiet seconds and ends when the client
goes or the engine stops. It reads only; opening one changes nothing.
Cookies¶
The engine keeps a cookie jar for design-mode requests (POST /execute and the
pm.sendRequest calls inside it), so a session set by one request is sent on
the next. One jar per environment, plus one for requests sent with no
environment selected; in memory only, for the life of the engine process, and
never written to disk. Load runs neither read nor write it.
A cookie set during a redirect chain stays with the origin that set it: it
is stored in the jar as any other, and a later hop of the same send carries it
only when that hop goes to the same origin - see POST /execute
for what a redirect that changes origin does to cookies. The Set-Cookie lines
of those intermediate hops are reported on the answer's redirects member,
whether or not a later hop carried them.
libcurl caps what it attaches: 150 jar cookies, and a Cookie line of 8190
bytes. A send that hits either still succeeds and says so in its warnings
(cookie_limit_reached, cookie_not_sent; see POST /execute):
the answer's, or for a streaming send, whose 202 carries none, the stored
trace's. The 8190-byte cap also drops the request's
typed Cookie rows, which share the line; the 150 cap does not.
libcurl also silently discards what a response sets past three limits: a
Set-Cookie line over 5000 bytes, a cookie whose name and value together pass
4096 bytes, and every cookie after the first 50 of one response. The answer (a
stream's stored trace) says so under warnings (cookie_dropped_oversized, cookie_dropped_too_many),
naming a dropped cookie and never its value. A request sent with
disableCookies has no jar and so no warning: libcurl's cookie engine is off
and drops nothing.
Under load the same three limits apply to a scenario load run's
per-virtual-user cookies, and what they drop is counted across the run in one
cookies_dropped run warning that names no cookie. A
single-request load run keeps no cookies, so it drops none. The two outgoing
caps above are not detected under load.
A storage failure answers 507, 503 or 500, never 400 - see
A storage failure is not a 400.
SameSite is parsed and ignored, on purpose: an API client has no cross-site
initiator to restrict, so every cookie whose domain, path and Secure flag
match is sent whatever its SameSite value (Strict, Lax or None).
GET /cookies¶
Every jar that holds anything, one entry per scope, in scope-key order (the no-environment jar first), each jar's cookies in its own line order.
A jar whose environment is in the Trash is left out of both forms
(issue #3349). The jar is kept, so
POST /trash/:id/restore brings the environment's
session back with it and it is listed again; a purge
(DELETE /trash/:id) drops it. The same goes for a jar
keyed by an environmentId that names no stored environment. The
no-environment jar is always listed.
Query Parameters:
- q, limit, offset (optional): one page of the cookies whose name or
domain holds q, in the {data, pagination} envelope - see
Paged lists. A page is flat: the scopes are walked in
the order above and each cookie row carries its scope's environmentId
beside the cookie fields ({environmentId, name, value, domain, path,
secure, httpOnly, expires}). A bad limit or offset is a 400
(invalid_limit, invalid_offset).
Response (none of the three):
{
"scopes": [
{
"environmentId": "env_staging",
"cookies": [
{
"name": "session",
"value": "abc123",
"domain": ".staging.example.com",
"path": "/",
"secure": true,
"httpOnly": true,
"expires": 1767225600
}
]
}
]
}
environmentId is null for the no-environment jar - null rather than "" so
a client cannot mistake it for an id. expires is unix seconds, or 0 for a
session cookie (one that lives until the engine exits). A scope with no cookies
left is not reported.
This route lists what a jar holds, not what a URL would carry. The URL-scoped
reads of the script API (pm.cookies, jar().getAll(url)) match a secure
cookie over https://, and over http:// only for localhost, 127.0.0.1
and ::1, which libcurl sends it to as trustworthy origins.
DELETE /cookies¶
Clear one jar, or all of them.
Query parameters:
| Parameter | Meaning |
|---|---|
| (none) | Clear every jar |
environmentId=<id> |
Clear that environment's jar |
environmentId= |
Clear the no-environment jar |
The three cases are the null-vs-absent rule in a query string: an empty value is a real scope - the one no id can name - and not a mistake.
Response:
cleared counts the cookies dropped; clearing a scope that holds nothing is a
200 with 0, not an error. Clearing every jar also clears the ones
GET /cookies leaves out because their environment is in the trash, and
cleared counts their cookies too: clearing everything leaves no credentials
behind.
Client certificates¶
An mTLS endpoint asks the client to present a certificate, and a certificate is
a property of where you are calling, not of one request - the transfer that
needs it is as often an OAuth token fetch, a redirect or a script's
pm.sendRequest as it is the request you are looking at. So the engine keeps a
registry of host to certificate and applies the matching entry itself, on every
outbound path: design sends, load runs, SSE streams, pm.sendRequest, the
OAuth token endpoint, POST /import/fetch and the monitor scrape. Nothing on a
request names a certificate.
Rows are read into the transport policy at the point of use, so a change reaches the next transfer without a restart - and, exactly like the proxy, a load run and a collection run read the registry once at run start and hold it, because libcurl reuses a pooled connection only when its TLS identity matches.
A redirect is matched hop by hop on a design send, a stream and a load run.
POST /execute (buffered or stream: true), the pm.sendRequest calls inside
it, the OAuth token fetch, a typed POST /import/fetch and every request of a
load run follow a redirect one transfer per hop, and the registry is asked about
each hop's own host and port: a send that starts at http://host and is
redirected to an mTLS https://host presents the entry that answers for the
second, and a hop no entry answers for presents nothing.
Matching is by host, and most specific wins. A host is either an exact
name (api.example.com) or the one wildcard form, *.example.com, which is
read as a label suffix: it answers for api.example.com and a.b.example.com,
never for example.com itself and never for notexample.com. That is the whole
syntax - a * anywhere else is a 400 naming the form, rather than a row
stored as a hostname no transfer can ever equal - and a wildcard never answers
for an address literal (127.0.0.1), which only an exact entry matches.
Three tiers decide which entry answers, closest host first:
| Tier | Beats | Example against api.eu.example.com:8443 |
|---|---|---|
| 1 | An exact host beats every wildcard | api.eu.example.com wins over *.eu.example.com, even if only the wildcard names the port |
| 2 | A longer wildcard beats a shorter one | *.eu.example.com wins over *.example.com |
| 3 | Within one host, the port beats the catch-all | *.example.com + port: 8443 wins over *.example.com + port: null |
The order is total, so the answer never depends on the order rows were added:
two entries can only rank equally by naming the same host and the same port,
and the second such write is a 409. Host comparison is case-insensitive (rows
are stored lower-cased), and an IPv6 host is registered without its brackets
(::1).
Paths, not contents. The row holds the paths of the certificate and key
files and the engine opens them at send time, so the private key never enters
the database. The passphrase is the one exception - it is stored, in plaintext,
the same as every other saved credential (see
db-schema.md) - and it is never sent
back: reads carry hasPassphrase instead.
Both file paths are checked when the entry is written, and an unreadable one is
a 400 naming the file. That is deliberate: a path that is not there otherwise
fails at handshake time as an SSL error against the endpoint, which reads as
"the API is broken" rather than "this setting is wrong".
A cert-authenticated exchange says so. POST /execute returns
clientCertificate on the response, the entry the final hop presented
("" when none matched it), and the stored trace carries the same value under
the same name, so a restored response names the entry a live one named. A
certificate is presented in a TLS handshake only, so the field is "" for an
http:// final hop whatever the registry holds for that host (#3260).
The row says what format its certificate is in, and the engine tells libcurl
so. certFormat is pem - a PEM certificate with its key in a second file -
or p12, a PKCS#12 bundle carrying both, and it becomes CURLOPT_SSLCERTTYPE
on every transfer. Which formats work is a property of the build's TLS backend:
| Backend | Builds | Presents |
|---|---|---|
| OpenSSL | Linux, macOS, Windows | pem and p12 |
| Schannel | none since issue #851 | p12 only |
Mutual TLS works on all three platforms as of issue #851. It did not before:
Windows built against Schannel, and curl's Schannel client-certificate path
cannot complete the handshake - it imports the bundle with
PKCS12_NO_PERSIST_KEY and the key that yields is one Schannel's credential
path cannot use, so the transfer failed with SEC_E_INTERNAL_ERROR ... The Local
Security Authority cannot be contacted (issue #842). Nothing in Vayu's
configuration changed that, so #851 changed the backend instead.
Before moving any leg back to Schannel, read closed issue #842. The defect
above is still open upstream: curl 8.21.0 carries two entries for it in its
own KNOWN_BUGS (curl issues 17626 and 3145), one of them naming the exact
call, and #842 is the measurement record - every driver, with a legacy-PBE and a
PBES2 bundle alike. A change that returns to Schannel has to re-instate the wire
skip #851 deleted. Schannel also takes no PEM pair at all, so a pem entry
would fail at handshake time again, which before issue #833 (when the engine
named no type) meant a Windows build could present nothing a user registered.
Both formats are asserted on a wire on every leg (a design send, an SSE stream,
a load run and a pm.sendRequest against a listener that demands a client
certificate).
A PKCS#12 entry names no key file, because the bundle carries the key: a row
that names one is a 400 rather than a stored path nothing would read, and
keyPath comes back "". The passphrase field covers both formats - libcurl
reads it as the PEM key's passphrase and as the bundle's import password.
The format is checked against the file, and defaulted from it. Leave
certFormat out and the engine reads the first bytes of certPath - a PEM
marker or the ASN.1 SEQUENCE a DER bundle opens with - and stores what it
found, falling back to pem for a file it cannot classify. Name it and it is
kept, but a contradiction (a bundle registered as pem, or the reverse) is a
400: the alternative is libcurl's parse error against the endpoint, which is
the misdiagnosis this registry exists to end. A file the engine cannot classify
is left for the backend to judge rather than refused here.
GET /client-certificates¶
Every registered entry; a trashed one is not listed.
Response:
[
{
"id": "cert_7f3c1a2b",
"host": "api.example.com",
"port": 8443,
"certPath": "/home/ada/certs/client.pem",
"keyPath": "/home/ada/certs/client.key",
"certFormat": "pem",
"hasPassphrase": true,
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"usable": true
},
{
"id": "cert_2b9d4e60",
"host": "internal.example.com",
"port": null,
"certPath": "/home/ada/certs/moved.pem",
"keyPath": "/home/ada/certs/moved.key",
"certFormat": "pem",
"hasPassphrase": false,
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"usable": false,
"problem": "certificate file '/home/ada/certs/moved.pem' is not a readable file"
}
]
port is null - not 0 and not omitted - for an entry that answers on every
port. keyPath is "" for a p12 entry, which stores no key path at all.
usable is whether the engine would present the entry, judged by the check
a write runs (and the transport policy re-runs on every row it reads) against
the files as they are now. A row can fail it after being written: a file moved
or deleted, or a row edited around the routes. The engine then leaves that
entry out of every send, and problem says why - the failed check's own
sentence, or for a certFormat the engine does not know, a sentence naming it.
problem is absent on a usable row. Only this list carries the two fields; the
POST and PUT responses do not, since those refuse an unusable row.
POST /client-certificates¶
Register a certificate for a host. Create only - the engine owns the id, so
a body carrying one is a 400 (see the engine owns every
id).
Body:
| Field | Required | Meaning |
|---|---|---|
host |
yes | Hostname, no scheme, port or path - or *.example.com for every subdomain of it. Stored lower-cased. |
port |
no | The port this entry is specific to; null or absent means every port. |
certPath |
yes | Path to the certificate file. Must be readable now. |
certFormat |
no | pem or p12. Absent or null reads it off certPath, falling back to pem. |
keyPath |
for pem |
Path to the private key file. Must be readable now, and must be absent for p12. |
passphrase |
no | The key's passphrase, or a PKCS#12 bundle's import password. Write-only. |
The uniqueness check and the write are one lock scope. Proving no other
row already claims this host + port and writing the new row happen under
one acquisition of the database lock, so two creates for the same target
racing each other cannot both pass the check before either writes - the second
is answered with the 409 below rather than landing beside the first.
Errors:
| Status | When |
|---|---|
400 |
A host that could never match (carries a scheme, a path, a port, or brackets, or a * outside the *.example.com form), a port outside 1..65535, a non-integer port, a missing host / certPath, a pem entry with no keyPath, a p12 entry that names one, a certFormat outside pem / p12, a certFormat the file's own bytes contradict, a file that is not readable, or a body id. |
409 |
Another entry already claims this host + port. Two rows for one target would make the certificate presented depend on row order, so the second is refused with the id of the first rather than silently shadowing it. |
A storage failure answers 507, 503 or 500, never 400 - see
A storage failure is not a 400.
PUT /client-certificates/:id¶
Update an entry. Update only - a missing id is a 404, never a silent
create. Merge-patch under the null-vs-absent
rule: an absent field keeps its value, port: null
widens the entry to every port, passphrase: null clears a stored one, and
keyPath: null clears the key path - which is how an entry moves from pem to
p12, since a bundle may not name one. certFormat: null re-reads the format
off certPath.
Validation runs on the merged row, not on the body, so a PUT that moves
only keyPath still proves the pair works together - and a PUT that names
certFormat: "p12" without clearing keyPath is a 400, because the merged
row would be a bundle naming a key file.
A storage failure answers 507, 503 or 500, never 400 - see
A storage failure is not a 400.
DELETE /client-certificates/:id¶
Delete an entry. The delete is soft (#2973): the row is stamped
deleted_at and GET /trash lists it, named by its target, until
a purge. From then on it is never presented: the transport policy reads live
entries only, so the next design send, stream, collection run or load run to its
host goes without it. Every route here treats the id as missing -
GET /client-certificates leaves it out, PUT and a second DELETE are a
404 - and its host + port is free for a new entry. The certificate and key
files themselves are never touched - the registry only ever held the way to
find them. The stored passphrase stays on the trashed row until it is purged.
Restore it with POST /trash/:id/restore, which is a
409 while a live entry claims the same host + port; destroy it for good
with DELETE /trash/:id, which is also what the startup
sweep does once trashRetentionDays has passed.
Response:
Errors: 404 if no live entry has that id, a trashed one included. A
storage failure answers 507, 503 or 500 - see
A storage failure is not a 400.
Allowed folders (file roots)¶
The folders a request-body file may be read from without being picked file by
file - one half of the trust rule,
beside the picked files.
Stored in file_roots (schema version 3); read once per design send and once
per run, so a change applies to the next send. POST and DELETE need the
grant secret in X-Vayu-Grant-Secret and answer 403
(grant_secret_required) without it, before the body is parsed; an engine
started without a secret refuses both. GET needs nothing.
GET /file-roots¶
Every allowed folder, ordered by path, as a bare array:
POST /file-roots¶
Allows a folder. Body: { "path": "/abs/dir" }. Create only; the engine owns
the id, so a body id is a 400.
201with the row.pathis stored canonical (symlinks resolved,.and..folded, no trailing separator).400whenpathis missing, not a string, not absolute, or not an existing directory.400when the canonical path is a filesystem or drive root (/,C:\), the user's home folder, or a folder that contains it (/home,/Users,C:\Users), the message naming which: each would allow nearly every file a request could name. Containment is by path component, case-folded on a drive letter. A folder inside the home folder is fine.409when the canonical path is already allowed, naming the existing row's id.
DELETE /file-roots/:id¶
Stops allowing a folder; the folder and its files are untouched.
{"success": true}, or 404 when no such row exists.
Picked files (file grants)¶
The files a person picked, each sendable from wherever it lies - the other
half of the trust rule,
beside the allowed folders (#2356). Stored in
file_grants (schema version 6); read once per design send and once per run,
like the folders. A grant is matched exactly against a reference's canonical
path, so it covers that one file and nothing beside it. POST and DELETE
need the grant secret in X-Vayu-Grant-Secret and
answer 403 (grant_secret_required) without it, before the body is parsed; an
engine started without a secret refuses both. GET needs nothing.
GET /file-grants¶
Every picked file, ordered by path, as a bare array:
POST /file-grants¶
Records a picked file. Body: { "path": "/abs/file" }. Create only; the
engine owns the id, so a body id is a 400.
201with the row.pathis stored canonical (every symlink resolved,.and..folded), so a link re-pointed after the pick no longer matches.400whenpathis missing, not a string, empty, holds a{{variable}}(a grant names one file, never a template), is not absolute, or is not an existing regular file - a directory, a device or a pipe is never granted.409when the canonical path is already granted, naming the existing row's id, as a second spelling of an allowed folder is.
DELETE /file-grants/:id¶
Forgets a picked file; the file itself is untouched, and a body naming it is
refused from then on unless an allowed folder holds it. {"success": true},
or 404 when no such row exists.
Transport diagnostics¶
POST /diagnostics/connection¶
Send one request under the transport policy in force and report which hop answered. Proxy, custom CAs and the client-certificate registry all fail at the first real request otherwise, and libcurl's message there names the endpoint rather than the setting - which is how "my API is down" gets filed against a proxy that was never configured correctly.
The probe is a HEAD, with verification on (that is the subject of the
test), redirects off (a redirect would move the test to a host the caller
never named and report its proxy and certificate as this one's) and a fixed
10-second deadline.
{
"url": "https://api.example.com/",
"outcome": "proxy_failed",
"errorCode": "PROXY_ERROR",
"detail": "Received HTTP code 407 from proxy after CONNECT",
"proxy": { "mode": "manual", "url": "http://corp.example:8080" },
"clientCertificate": ""
}
| Field | Meaning |
|---|---|
outcome |
ok, proxy_failed, tls_failed, timed_out or failed. Deliberately coarser than ErrorCode: these are the answers that lead a reader to a different setting. proxy_failed covers every PROXY_ERROR: an unresolvable or down proxy, a refused CONNECT, and a forwarding proxy's 407 on an http:// target. |
proxy.mode |
The proxyMode in force. Always present. |
proxy.url |
The proxy the probe went through, with its user:password@ removed (the body reaches a screen and an agent's context). Absent when the probe went direct. Under manual, and system with a resolved URL, it is the setting in force, left out when the probe completed without a proxy (a proxyBypass entry); a probe that failed still names it, since a failure at the proxy hop may not read as proxied. Under environment, and system with nothing resolved, it is what libcurl read from http_proxy / https_proxy / all_proxy for the target's scheme - reported only when libcurl really proxied the probe (CURLINFO_USED_PROXY), so a no_proxy exemption reads as direct. |
proxy.source |
"environment" when proxy.url is not a Vayu setting: libcurl chose the proxy from the process environment. Absent otherwise. With source set and no url, the probe was proxied but the variable could not be read back. |
clientCertificate |
The registry entry that answered for this host, "" when none did - always so for an http:// probe, since a certificate is presented in a TLS handshake only (#3260). Always present, like POST /execute's. |
status |
The status line. Present only on ok. |
errorCode / detail |
The engine's ErrorCode spelling and the message: libcurl's own, or for a forwarding proxy's 407 on an http:// target (#3257) the engine's sentence naming the proxy. Absent on ok. |
A failed connection is a 200. The test succeeded in answering; only a
malformed body or a URL that is not http/https is a 400.
It never returns the response body, headers or redirect chain, and a test
asserts that. This is a diagnostics surface on the localhost API, not a general
fetch proxy - that is POST /import/fetch, behind its own byte bound.
Webhook Inbox¶
An inbox is a second HTTP listener the engine opens on request. It accepts any method on any path, records what arrived, and answers a canned response - nothing else. That is what makes testing the receiving side of a webhook a local operation: point the sender at the inbox URL instead of a cloud tunnel, and the payload never leaves the machine.
Lifetime is the engine process. An inbox is not a stored resource: there is
no create/update split (POST creates, PUT updates
applies to collections, requests and environments), ids are not restorable
across restarts, and POST /inbox/start is a verb path for that reason. Stopping
an inbox frees its listener but keeps the record - and therefore its captures -
readable until the engine exits; DELETE /inbox/:inboxId is what removes both.
After an engine restart the app names the inboxes, issuers and mocks that
stopped with it in one notice (app/src/lib/services-stopped-by-restart.ts).
Binding is a trust decision. The default is 127.0.0.1. Any other address
is refused unless the caller also sends "confirmNonLoopback": true, and the
inbox reports loopback: false from then on so a client can badge it. See
architecture.md for why only the inbox listener may
bind wide and the management API never may. An inbox holds at most 96
connections at once: 32 being served (a canned delayMs wait occupies one for
its whole duration) and 64 waiting for one. A connection past that is closed at
accept, which the sender sees as a reset, so an inbox bound past loopback
cannot be held open by idle connections until the engine runs out of file
descriptors. Every other on-demand listener (mock server, mock issuer, OAuth
callback) has the same bound.
Bounds. Three are settings (GET/POST /config, category Services),
read once when an inbox starts - so a change applies to the next inbox
started, and a running listener keeps what it was started with:
| Setting | Default | Range | What it bounds |
|---|---|---|---|
inboxMaxBodyBytes |
65536 | 256 - 8388608 | Stored body per capture. Past it the body is kept as a prefix with bodyTruncated: true, cut on a character boundary so a prefix of text is still text; bodyBytes is always the size as received |
inboxMaxCaptures |
500 | 1 - 10000 | Captures retained per inbox, oldest evicted first. Also the ceiling on one limit of the capture list |
inboxLivePollIntervalMs |
250 | 25 - 5000 | How often a watched inbox checks for new captures - the delay between a webhook landing and its event |
Three are not settings, deliberately. A request over 8 MiB is refused at
the transport with a 413 and recorded nowhere: that bounds what an
unauthenticated remote caller can make the engine buffer, which is not the local
user's preference to spend. The canned response's delayMs is capped at
30000: it holds a listener thread for its whole duration. A stop, a delete or
the engine shutting down ends the delay at once, and the canned answer then goes
out without the rest of it. The request
target - path and query together - is capped at 8192 bytes by the
transport, past which it answers 414.
The transport also answers 400, closes the connection and records nothing for
a request it cannot read unambiguously (RFC 9112 §3): a request line whose parts
are not separated by single spaces, a request target holding a #, an
HTTP/1.1 request with no Host, a request with more than one Host or with a
byte outside uri-host [ ":" port ] in it. A request carrying both
Transfer-Encoding and Content-Length is captured and answered, and then the
connection is closed. The request line and headers together must arrive within
5 seconds.
Below that cap the path's length does not matter, and "any path" is meant literally: an inbox routes every request to its capture without matching the path against anything, so a signed callback URL, a per-delivery token in the path or a deeply nested tenant route is recorded like any other (issue #1140).
A multipart/form-data body (a file upload, curl -F) is captured raw, as
sent, with its boundaries and parts, and is cut at inboxMaxBodyBytes like any
other body (issue #3110). An application/x-www-form-urlencoded body is captured
the same way up to the 8 MiB transport ceiling rather than refused at 8192 bytes
with an empty 413 (issue #3111). The capture's Content-Type header is the
sender's.
A compressed body is stored as sent. A sender that declares
Content-Encoding: gzip, deflate, br or zstd (an OpenTelemetry or Sentry
exporter, a log shipper) is captured and answered with the canned response like
any other; the inbox does not decompress, so body holds the compressed bytes
(base64, as any non-text body is), bodyBytes is their compressed size, the cut
at inboxMaxBodyBytes applies to them, and the capture's Content-Encoding
header is the sender's. Only the inbox listener does this: the management API
refuses a compressed request body, and an unrecognised coding such as
identity was always passed through.
CORS follows the inbox's allowedOrigins (issue #2367), the same policy a
mock server applies (see Mock Server), so a browser-hosted
sender can read the canned response:
- None listed (the default): every answer carries
Access-Control-Allow-Origin: *andAccess-Control-Expose-Headers: *, whatever the request'sOrigin, and neverAccess-Control-Allow-CredentialsorVary. Every page in the browser can read the canned response; none can read one sent with the user's cookies. - A list: a request whose
Originis a listed origin gets thatOriginechoed,Access-Control-Allow-Credentials: trueand the rest of the answer below. Any other request - an unlisted origin, the literalnulla sandboxed frame orfile://page sends, noOriginat all - is still captured and answered, with noAccess-Control-*header, so the browser keeps the answer from the page.Vary: Originis on every answer under a list. Origins are compared canonically: scheme and host case-folded, a default port dropped, sohttps://App.Example:443matches a listedhttps://app.example.
A real preflight (a request carrying Access-Control-Request-Method) is
answered 204 and never reaches the capture, the canned delay or the canned
status - a preflight must get a 2xx or the browser aborts before the real
request arrives, so a canned response configured with a non-2xx status (to
exercise a sender's retry path) would otherwise break every browser-hosted
sender silently. It carries the grant above (and Access-Control-Allow-Methods
/ -Allow-Headers echoing what was asked, Access-Control-Max-Age: 600), or
under a list for an unlisted origin no CORS header at all. A header the canned
response sets that names Access-Control-* or Vary is dropped rather than
echoed, since the engine already answered those and a replayed grant would undo
a refusal; a credentialed answer (a listed origin) rewrites the wildcard
Access-Control-Expose-Headers into the canned response's own header names,
per the Fetch spec's rule that * there is a literal name, not a wildcard,
under credentials.
POST /inbox/start¶
Start a listener. Every field is optional - an empty body starts a loopback
inbox on a free port that answers 200 with no body.
Request:
{
"port": 0,
"bind": "127.0.0.1",
"confirmNonLoopback": false,
"allowedOrigins": [],
"response": {
"status": 200,
"body": "",
"headers": {},
"delayMs": 0
}
}
| Field | Meaning |
|---|---|
port |
0 (default) picks a free port |
bind |
Default 127.0.0.1; anything outside 127.0.0.0/8 and ::1 needs confirmNonLoopback. Loopback is decided by parsing the address, so a hostname that merely starts 127. (or localhost.example.com) is not loopback and needs the confirmation. 0.0.0.0, :: and [::] bind every interface; the response then names where to send (reachableAt, below) |
response.status |
100-599 |
response.headers |
String values only; a Content-Type here is used verbatim |
response.delayMs |
0-30000, applied before every reply |
allowedOrigins |
Default [] (CORS *, no credentials). Up to 32 origins granted credentialed CORS, each http:// or https:// plus a host and an optional port, at most 512 bytes: no path (a trailing / included), query, fragment, user name or password, no * and not null. Stored and echoed canonical (scheme and host lowercased, a default port dropped); fixed for the inbox's life, PUT does not change it |
An out-of-range value is a 400 naming the field rather than a fallback to the
default: a listener quietly answering something other than what it was asked to
is invisible on both sides of the wire. A bind that fails is a 409 with code
inbox_bind_failed; a non-loopback bind without confirmation is a 400 with
code inbox_non_loopback_bind. An allowedOrigins that is not an array, holds
too many entries, or holds one that is not an origin is a 400 bad_request
naming the entry (allowedOrigins[1]) and what is wrong with it.
A port another engine listener is already running on - an inbox or a mock
issuer - is refused with that same 409, naming the holder ("inbox inbox_2f1c
is already listening there"). The engine checks that itself rather than letting
the bind report it: listeners are bound with SO_REUSEPORT, so on Linux a
second bind on the same address and port succeeds and the kernel then splits
arriving connections between the two listeners, each capturing an effectively
random half. A port held by a process outside the engine is still reported by
the bind (Couldn't bind <address> - the address may be in use or
unavailable); port: 0 is never refused this way, since the kernel does not
hand out a port it is already using.
Response:
{
"inboxId": "inbox_2f1c...",
"url": "http://127.0.0.1:41235/",
"bind": "127.0.0.1",
"port": 41235,
"running": true,
"loopback": true,
"captureCount": 0,
"allowedOrigins": [],
"response": { "status": 200, "body": "", "headers": {}, "delayMs": 0 }
}
captureCount is how many captures the inbox is holding right now - what a
DELETE /inbox/:inboxId would destroy with it. Every route that returns an
inbox fills it, so a client can word a confirmation without a second round trip.
url is where a sender sends, which is the bind address unless the inbox is
bound to every address (0.0.0.0, :: or [::], each needing
confirmNonLoopback): that is no address a sender can use, so url is the
first non-loopback IPv4 address of the machine, and reachableAt lists a URL
for every one (the machine has several; url is only the first the OS names):
{
"url": "http://192.168.1.20:41235/",
"bind": "0.0.0.0",
"reachableAt": ["http://192.168.1.20:41235/", "http://10.0.0.7:41235/"]
}
reachableAt is on the wire for a wildcard bind only, and lists IPv4
addresses only. A
machine with no non-loopback IPv4 address reports reachableAt: [] and a
url on 127.0.0.1. It is read from the interfaces each time the inbox is
read, not fixed at start, so it follows a change of network.
GET /inbox¶
Every inbox this process has started, running or stopped: {"data": [ ... ]},
each entry the object above.
PUT /inbox/:inboxId¶
Update the canned response, live - the next caller receives the new one, with no
restart and no captures lost. Merge-patch: an absent field keeps what the inbox
is serving. The body may be the response object itself or {"response": {...}},
so a client can send back what start handed it. 404 for an unknown id.
Atomic against a concurrent update, the same guarantee the resource PUTs
above give (issue #1454): the read, the merge and the write are one acquisition
of the inbox's own lock, not the database's - the canned response lives in
memory - so two clients patching one inbox at the same moment each merge onto
what the other just committed rather than onto the response as both of them
found it.
POST /inbox/:inboxId/stop¶
Stop the listener. Returns the inbox with running: false. Captures survive;
404 for an unknown id. A stop is not a delete - DELETE /inbox/:inboxId is.
DELETE /inbox/:inboxId¶
Stop the listener, drop the record, and delete its captures with it:
{"inboxId": "...", "capturesDeleted": 12}. 404 for an unknown id.
A running inbox is stopped rather than refused - one call, because the caller's intent is that the inbox be gone. That is safe rather than racy because the teardown joins every in-flight handler before returning, so nothing can still be capturing when the rows are cleared. The order is stop, then clear, then drop the record: a database failure therefore leaves the inbox in place - stopped, and deletable again - rather than orphaning captures no inbox could list.
The captures dying with the record is the point, and is why stop keeps them:
they go by explicit user intent here, instead of the record living to the end of
the process to protect them. There is deliberately no restart route: delete
and start a new inbox. A restart would have to decide what happens to the
existing captures, and this way the user decides.
GET /inbox/:inboxId/requests¶
The captures, newest first, in the standard {data, pagination} envelope.
Query parameters: limit (default 50, capped at 500), offset (default 0).
{
"data": [
{
"id": 12,
"inboxId": "inbox_2f1c...",
"receivedAt": 1767225600000,
"method": "POST",
"path": "/hooks/order",
"query": "attempt=2",
"headers": { "Content-Type": "application/json" },
"body": "{\"id\":7}",
"bodyEncoding": "utf8",
"bodyBytes": 8,
"bodyTruncated": false,
"remoteAddr": "127.0.0.1"
}
],
"pagination": { "total": 1, "limit": 50, "offset": 0, "hasMore": false, "returned": 1 }
}
id is the capture's storage id and also its SSE event id (see below).
headers joins a repeated name with ,. query is the raw query string
without the ?.
bodyEncoding says how to read body (issue #3109). A JSON string holds
only UTF-8 and a sender can post any bytes, so "utf8" means body is the
stored text itself, and "base64" means the stored bytes were not valid UTF-8
text (or held a NUL) and body is their standard, padded base64. It is decided
when the capture is read, so every capture carries it, and bodyBytes is the
size as received in both cases, never the length of the encoded string. A body
the byte cap cut is first trimmed back to a character boundary, so a cut inside
a multi-byte character leaves utf8 text rather than turning the whole prefix
into base64; bodyTruncated still says it was cut. path and query are
recorded raw, exactly as the sender spelled them: percent-escapes such as %2F
and %20 are kept, so a signature over the path or a copied capture URL still
matches the request received. Neither is classified: a byte in either that is
not UTF-8 is answered as U+FFFD.
DELETE /inbox/:inboxId/requests¶
Clear the captures, keeping the listener: {"inboxId": "...", "cleared": 12}.
GET /inbox/:inboxId/live¶
Server-Sent Events, one event per capture, each carrying the same object as the
list above (bodyEncoding included) and an SSE id: equal to the capture's id. A reconnect that sends
Last-Event-ID resumes after that capture, so nothing is missed across a drop.
The stream ends when the inbox is stopped.
?lastEventId=<id> is the same resume point as a query parameter, for a
client that reconnects by hand: browser EventSource sets Last-Event-ID only
on its own retry and exposes no way to set a header on a fresh connection. The
header wins when both are given, being the more recent of the two. A value that
is not a non-negative capture id is refused with 400 and code
invalid_last_event_id rather than resumed from the start, which would replay
every retained capture as though it had just arrived.
One stream per inbox. A second concurrent watcher is refused with 409 and
code inbox_live_in_use: each SSE handler occupies a cpp-httplib pool thread
for its whole life, so N watchers on one inbox is N parked threads.
A claim whose holder stopped writing is taken over, not refused. A stream
learns its socket died only when its next write fails, up to one
inboxLivePollIntervalMs later, so a client reconnecting inside that window used
to meet a 409 it could not recover from. A holder that has not written
successfully for two poll intervals (at least 100ms) is not writing, and its slot
goes to the newcomer; the evicted stream ends on its next write. Every live
stream writes at least a keep-alive each interval, so a genuinely live watcher is
never evicted and a second concurrent one is still refused.
Mock Server¶
A mock server is a listener that answers a collection's saved examples on the paths its requests describe. It is what examples are for: import a spec, and the responses it documented become a running upstream you can build a frontend against, or point a Vayu load run at, without a cloud plan or a second machine.
A mock serves the stored body verbatim, including a partial one. An example
whose bodyTruncated is true holds only the first slice of the response it was
captured from, and the mock answers with those bytes and the recorded headers as
though they were a whole response - nothing on the wire says otherwise, and the
flag deliberately does not change what is served. It is disclosure, not
behaviour: the app paints a "Partial body" chip on the row so the choice to serve
it is a made one (issue #659).
A 204 or 304 example is served with no body, no Content-Length and no
Content-Type (RFC 9110 §6.4.1), whatever its stored body says; the rest of
its headers are kept. The same holds for a 1xx example stored before create
began refusing them (#3117). A real preflight's synthesized 204 carries no
Content-Length either.
Example bodies are served literally. A {{variable}} or a dynamic value such
as {{$guid}} in a stored body or header is sent as those characters: the mock
resolves no variables, unlike Postman's mock servers, which a collection moving
from Postman may expect. Resolving them would be a feature, not a docs fix.
Lifetime is the engine process, exactly as for an inbox and an issuer - a
verb path starts it, ids are not restorable across restarts, and stopping one
drops its record. There is no stopped state to read: a mock holds nothing
that outlives its listener, unlike an inbox and its captures. Trashing the
collection a mock serves, or any collection above it, stops the mock the same
way (DELETE /collections/:id), and a restore does
not start it again. A mock an engine restart stopped is named in the app's
restart notice, as an inbox is.
Load-testing against a mock is a supported workflow, and it is the one this listener exists for as much as frontend development: a mock is a known-latency, zero-cost upstream on the same machine, so a run against it measures the generator rather than someone else's service, and costs nobody a bill. Start the mock, then point a run at one of its paths:
curl -s localhost:9876/mock/start -d '{"collectionId":"col_abc123","latencyMs":5}'
# -> {"mockId":"mock_5f2a","url":"http://127.0.0.1:43117", ...}
curl -s localhost:9876/runs -d '{
"mode":"constant_rps","targetRps":500,"duration":"30s",
"url":"http://127.0.0.1:43117/pets","method":"GET"
}'
latencyMs is what makes the baseline realistic rather than degenerate, and
errorRatePct is how a run's error handling and threshold
verdict get exercised without breaking a real service.
Loopback only. There is no bind field. Unlike an inbox - which serves
capture-and-echo and nothing else, so a LAN-visible one is defensible - a mock
re-serves stored response bodies verbatim, and a recorded response can carry
whatever the real one did. See architecture.md.
The route table is a start-time snapshot. It is built once, from the collection and every collection under it (an OpenAPI import files its requests in a folder per tag, so the subtree is the only useful unit), and a running mock does not reload edits: stop it and start it again. An example saved from the app's response viewer (issue #588) is an edit like any other - it is appended after the request's existing examples, so a restart keeps answering with the same first one, and the new row is only reachable once the mock is restarted.
How a request is matched.
- The stored URL is reduced to a path: scheme and host - or the
{{baseUrl}}variable standing in for them - the query and the fragment are all dropped. A leading variable goes whole and is never resolved, so a path carried inside its value is lost: withbaseUrlset tohttps://x/v1, a request stored as{{baseUrl}}/petsis mocked at/pets, not/v1/pets, and a caller that keeps/v1in its URL matches no route. Put the prefix in the stored URL ({{baseUrl}}/v1/pets) to have the mock serve it. - All three template spellings are one wildcard segment:
{{petId}}(Vayu and Postman),{petId}(OpenAPI) and:petId(Postman's other form). A wildcard matches exactly one non-empty segment. The normalization is pinned to the importers' own byengine/tests/fixtures/path-template-conformance.json, which both suites read - the app writes these URLs and the mock reads them back. - Specificity wins, not registration order:
/pets/mineanswersGET /pets/mineeven when/pets/{{petId}}was stored first. - A trailing slash and a repeated
/are the same route. - Requests that share a method and path are one route (#3115). The query
is dropped, so
GET /q?kind=aandGET /q?kind=b(a Postman collection's "login ok" and "login fail") cannot be told apart: one of them answers both and the other shows0hits for good. Among routes of equal specificity the first that has a saved example answers, else the first in sidebar order, so an example-less request listed above one with an example no longer turns the path into a501. Two routes are duplicates only when they have the same method, the same number of segments and the same literals in the same positions (a wildcard's name does not count):/a/{{x}}/band/a/b/{{y}}are equally specific but answer different paths, so neither is shadowed. The start response counts the shadowed requests (duplicateRoutes) andGET /mock/:mockId/routesmarks each one and names the request that answers in its place. - A
HEADis answered by theGETroute of that path (#3118) when noHEADrequest is stored for it: the GET's status and headers (itsContent-Lengthincluded) and no body, socurl -Ion a mocked path works. A storedHEADrequest still wins.
What a miss says. The message is most of the debugging value, so the three outcomes are distinct rather than one blanket 404:
| Case | Status | code |
Message names |
|---|---|---|---|
| No request has that path | 404 | mock_no_route |
The method and path, and how many routes are served |
| The path matches, the method does not | 404 | mock_method_mismatch |
The matching path template and the methods it is served for |
| A route matched but its request has no saved example | 501 | mock_no_example |
The request's name, and that an example must be saved or imported |
CORS follows the mock's allowedOrigins (issue #2367). A mock server
answers whatever calls it - most often a browser page on another origin, not
only curl - and what it answers with is often a recorded response, so which
pages may read it is the caller's to state:
- None listed (the default): every response carries
Access-Control-Allow-Origin: *, whatever the request'sOrigin, plusAccess-Control-Expose-Headers: *so a page'sfetchcan read a header the example set, and neverAccess-Control-Allow-CredentialsorVary. Every page in the browser can read the mock; none can read a response sent with the user's cookies. - A list: a request whose
Originis a listed origin gets thatOriginechoed withAccess-Control-Allow-Credentials: true, andAccess-Control-Expose-Headersnames the example's own headers, since the Fetch spec reads*there as a literal name, not a wildcard, once credentials are in play. Any other request - an unlisted origin, the literalnulla sandboxed frame orfile://page sends, noOriginat all - is still served, with noAccess-Control-*header, so the browser keeps the response from the page.Vary: Originis on every response under a list. Origins are compared canonically: scheme and host case-folded, a default port dropped, sohttps://App.Example:443matches a listedhttps://app.example. A list also pins theHost: the mock answers403to any request, a preflight included, whoseHostis not127.0.0.1:<port>,localhost:<port>or[::1]:<port>of its own port (the management API's rule), so a page that DNS rebinding has made same-origin with the mock cannot read it. A mock with no list answers anyHost.
A header the example itself carries under Access-Control-* or Vary is
dropped rather than echoed, since the engine already answered those and a
replayed grant would undo a refusal. The grant applies to a miss too - a 404
with no CORS headers reads in a browser as an opaque "CORS error" instead of
the mock_no_route / mock_method_mismatch / mock_no_example body above.
A real preflight - a request carrying Access-Control-Request-Method -
is always answered synthetically (204, with the grant above plus
Access-Control-Allow-Methods / -Allow-Headers echoing what the browser
asked for and Access-Control-Max-Age: 600, or under a list for an unlisted
origin no CORS header at all), whether or not a route is stored for that
path under OPTIONS: breaking the preflight to surface a stored route's
404/501 would break the browser request behind it for nothing. It does
not count toward a route's hits or appear in GET /mock/:mockId/activity.
A plain OPTIONS request carrying neither header is ordinary traffic and is
served or missed like any other verb.
Bounds (rails, not settings): at most 8 mock servers at once (a listener
thread each), at most 2000 routes in one table, and latencyMs capped at
30000 - it holds a listener thread for its whole duration, until a stop
ends it.
POST /mock/start¶
Request:
{
"collectionId": "col_abc123",
"port": 0,
"latencyMs": 0,
"errorRatePct": 0,
"allowedOrigins": []
}
collectionId is required. port 0 (the default) binds a free one.
latencyMs (0 - 30000) delays every answer; errorRatePct (0 - 100) replaces
that share of answers with a synthesized 500 carrying mock_injected_error.
allowedOrigins (default []) lists up to 32 origins granted credentialed
CORS (see above), each http:// or https:// plus a host and an optional
port, at most 512 bytes: no path (a trailing / included), query, fragment,
user name or password, no * and not null. It is stored and echoed
canonical (scheme and host lowercased, a default port dropped). Every
out-of-range value is a 400 rather than a clamp, and an allowedOrigins
entry that is not an origin is a 400 bad_request naming the entry
(allowedOrigins[1]) and what is wrong with it.
Response:
{
"mockId": "mock_5f2a",
"collectionId": "col_abc123",
"collectionName": "Pet Store",
"url": "http://127.0.0.1:43117",
"port": 43117,
"latencyMs": 0,
"errorRatePct": 0,
"routeCount": 12,
"routesWithoutExample": 3,
"duplicateRoutes": 0,
"createdAt": 1735689600000,
"allowedOrigins": []
}
url has no trailing slash - it is a base to concatenate a path onto.
routesWithoutExample is the number that explains an otherwise empty-looking
mock, which is why it is reported rather than left to be discovered one 501 at
a time. duplicateRoutes is the number of requests shadowed by another with
the same method and path (see above): rows that can never answer, whatever
their query says. It is 0 for a collection with none.
Errors: 404 for a collection that does not exist; 400
mock_no_requests when the collection and its subtree hold none (a listener
that 404s everything is never what the caller meant); 400
mock_too_many_routes past the table bound; 409 mock_limit_reached at the
server budget; 409 mock_bind_failed when the requested port is taken,
naming the holder when this engine is the one holding it.
GET /mock¶
{"data": [...]} - every running mock, in the shape above.
GET /mock/:mockId/routes¶
The table the mock is serving. This is how "the mock 404s that path" gets diagnosed without sending a request per guess.
{
"data": [
{
"requestId": "req_1",
"requestName": "Get pet",
"method": "GET",
"path": "/pets/{{petId}}",
"hasExample": true,
"mode": "first",
"hits": 3,
"status": 200,
"exampleName": "200 OK"
}
]
}
status is 0 when hasExample is false - there is no example whose status it
could be. mode is the request's mock_response_mode ("first" / "fixed" /
"random"); hits is how many times this route has answered a request, since
the mock started. exampleName is the example that would answer for "first"
or "fixed" - it is absent for "random", since which one answers varies per
request. 404 for an unknown mock.
A request that shares its method and path with another (see "How a request is
matched") is shadowed: its row carries "shadowed": true and "shadowedBy":
{"requestId": "req_2", "requestName": "login ok"}, naming the request that
answers for both. Both members are absent - not false - on every row that
is not shadowed, including the one that answers. A shadowed row keeps
hits: 0, and its hasExample / status describe its own examples, which are
never served.
GET /mock/:mockId/activity¶
What this mock has served, newest first: {"data": [...]}, at most limit
entries (query param, default 50, capped at 200; a non-numeric value is
a 400). Each entry is one inbound request, whichever of the three ways it was
handled:
{
"data": [
{
"at": 1735689600123,
"method": "GET",
"path": "/pets/1",
"requestId": "req_1",
"requestName": "Get pet",
"exampleId": "ex_1",
"exampleName": "200 OK",
"status": 200,
"injectedError": false
}
]
}
requestId / requestName are null when nothing in the route table matched
the path at all, and also for an injected failure (injectedError: true):
the error-rate roll happens before route resolution, so an injected 500 never
reaches route matching, even when a route would have matched. exampleId /
exampleName are null alongside them, and also when the matched route had
no saved example (status: 501).
injectedError: true marks a synthesized errorRatePct failure. 404 for an
unknown mock. Like the route table, this log is discarded when the mock stops -
there is nothing to read after that.
POST /mock/:mockId/stop¶
Stops the listener and drops the record: {"mockId": "...", "stopped": true},
or 404. In-flight answers are joined before this returns; one inside its
configured latencyMs is answered at once, without the rest of the delay.
Authentication¶
The engine resolves auth server-side. Every request's auth object (on
POST /execute and POST /runs) is applied to the outgoing request before it
hits the wire:
auth.mode |
Effect |
|---|---|
none / inherit |
No-op (inherit is resolved by POST /compose before it reaches an execution endpoint; one arriving unresolved is a warning in the logs) |
bearer |
Authorization: Bearer <token>, the token trimmed of the spaces and tabs around it (#2467); a token empty once trimmed writes no header at all and the send carries an authNotice saying so (#3203) |
basic |
Authorization: Basic <base64(user:pass)>, as typed - a password may end in a space |
apikey |
Header key: value, or ?key=value when in: "query"; the key and the value are trimmed of the spaces and tabs around them (#2467); a key empty once trimmed writes nothing and the send carries an authNotice saying so (#3203) |
oauth2 |
Acquires/caches a token (below) and injects it per tokenPlacement; a token placed in the header yields to an Authorization header the request carries, and is then not fetched at all (#3202, below) |
any other mode (digest, aws, ntlm, hawk, oauth1, edgegrid, jwt, which an import can store) |
Not executed: the request is sent without authentication, never refused, and the /execute answer and the stored trace carry an authNotice saying so (#2474) |
When it is applied. As the request is built, before any pre-request script
runs - so the script's pm.request holds the header - unless a credential
(a bearer token, a basic username or password, an apikey key or value)
still holds a {{name}} that is not a data column or the iteration identity.
Such a name is one composition found no variable for, or any name a scope
answers in a request a pre-request script runs before (it is listed in
deferredVariables) or in a step of a collection run
whose plan writes a variable (Scenario runs), and that auth is applied
after the pre-request script and the residual-token pass instead, each
credential resolved against the scopes as the script left them (#2473, #2521),
so pm.environment.set("password", …) reaches a basic pair before it is
base64-encoded. That is Postman's order; the script then does not see the header
in pm.request.headers, and an Authorization it sets wins by the rule below.
A data column or the identity in the same credential is bound first. A name
nothing answers is encoded as written. A script that assigns pm.request.auth
replaces this block in either case: the credential applied before it is taken
off, a waiting one is never applied (#3131, see
Mutating the request).
oauth2 follows the same order on a single send and a collection run's step
(#2521). A config in a request that a pre-request script runs before (on a
sequential run, in any step of a plan that writes a variable), or holding a
{{name}} that nothing defines, is left as written by
POST /compose, resolved in every string after the
pre-request script, and only then is its token acquired; the token cache key is computed from
that resolved config, so a script that sets a clientId or an accessTokenUrl
selects its own cached token, and a client secret or scope it sets reaches the
token endpoint when a token is fetched (neither is part of the key, so a token
already cached under the same key is reused). The wait on the identity
provider is left out of engineMs, as a fetch at the build is, and a token that
cannot be acquired answers authErrorCode as it does at the build. A
load run acquires its token once, when it is planned and before any script
runs, from the stored values: its composition (deferDynamicVariables)
resolves the config, and a name nothing defines is refused with a 400 that
names it (invalid_run_config for a single request, invalid_scenario for a
collection). A script that sets an OAuth 2.0 variable has no effect under
load, however many iterations or virtual users run it, and nothing is
re-acquired per iteration; the one change to a run's token after it starts is
the mid-run refresh of the token cache. The same order
holds wherever a script can run between the build and the send:
| Send | Applied after |
|---|---|
POST /execute (buffered and stream: true) |
the pre-request script |
| A collection run's step | that step's pre-request script, each iteration |
| A collection load run's step | that submission's step.before elements (an inline script.pre) and the residual pass over its virtual user's scope |
A single-request load run declaring requestElements whose submissions are copied (a step.before kind, data rows, a bind token or deferred auth) |
that submission's step.before elements and the residual pass over the run's scopes (a script.setup included) |
A single-request load run without requestElements has no such pass. When it
names an environmentId or a requestId, the build leaves such credentials
alone and its start-of-run pass (POST /runs) resolves and
applies them once, after the request's own names, so a basic pair and a
query-placed api key are encoded with their values (#3288); without either, the
build encodes the name as written. Under load a name nothing answers is never a
refusal: it is sent as written and counted like any other unresolved token
(#1503), except inside a basic pair's base64, where it never was countable.
An apikey with in: "header" whose key is not a header name once trimmed
(X Key) is refused, with nothing written: the failure is AUTH_FAILED with an
authErrorCode of invalid_header_name. The message names the offending byte
and not the key, which arrives already resolved and may be a secret. An apikey whose key is empty or
only padding, in the header or the query, and a bearer token that is empty or
only padding are not refused: nothing is written (never Authorization: Bearer
with nothing after it), the request is sent without that credential, and the
send carries an authNotice saying so (#3203), so a variable
left unset on purpose does not fail a run. A token or key that resolves empty
after the pre-request script is judged the same way. A bearer token with
spaces inside it keeps them: only the ends are trimmed.
A user-supplied header always wins over the one auth would write: Authorization
over bearer/basic/oauth2, and a header named like the API key's key over
apikey (in: "header"; the key name is matched against the request's own
headers). Header names are matched case-insensitively, so authorization or
x-key against X-Key counts. A query-located API key is a URL parameter and is
appended regardless. The app's code snippets apply the same rule
(engine/tests/fixtures/auth-header-precedence.json).
An oauth2 block whose token goes in the header fetches nothing when the
request already carries an Authorization header (#3202). The header the
request typed is sent, no token is acquired, and the token cache, the
targetPolicy and the endpoint are not consulted, so a token endpoint that is
down, refused by the policy or unreachable cannot fail the send. The send says
so: authNotice reads the request's own Authorization header was sent; no
OAuth 2.0 token was fetched (see authNotice), and no
Authorization is recorded as written by auth. The rule holds wherever auth is
applied: at the build, after a pre-request script, in a collection run's step,
and in a load run, whose POST /runs pre-flight reads the payload's headers the
way the run will and so does not fetch (or fail on) a token it would not send.
It applies to the Authorization header only: an oauth2 block with
tokenPlacement: "query" writes a URL parameter, has nothing to yield to, and
is fetched and appended as before. The header is read when auth is applied, so
one a pre-request script sets spares the fetch only when the auth waits for that
script (When it is applied); otherwise the token was already
fetched and the script's header replaces what auth wrote.
Redirects. With followRedirects on, a redirect to a different scheme, host
name or port drops the Authorization header and a typed Cookie, so
bearer, basic and an oauth2 token placed in the header stop at the first
origin.
Nothing else is dropped: an apikey with in: "header" - and any other header
the request carries - is sent to the origin the redirect leads to, including
over http after an https hop. That is a documented exception, not an
oversight: it is the rule libcurl applied while it followed redirects, kept as
it was. A design send, a stream and a load run all run the engine's own
redirect loop, so the three cannot disagree about what reaches the next
origin. A query-located
key is part of the URL as sent; the next hop is whatever the response's
Location names, so the key reaches it only if that URL repeats it. Set
followRedirects: false on a request whose key must not leave the origin it was
sent to; the app says this beside the API Key fields.
A design send makes the downgrade visible: each entry of the answer's
redirects records the url its request went to and schemeDowngrade, true
when that request was https and the next one http (see
redirects) and pm.response.redirects shows them to a
post-request script. A load run and a stream record no hops.
(engine/tests/redirect_credentials_test.cpp)
OAuth 2.0 token cache¶
Tokens are acquired once and cached (SQLite oauth_tokens, keyed by a
deterministic cacheKey = accessTokenUrl \x1f clientId \x1f credentialsId \x1f
username-if-password-grant, then one segment per extra parameter list that has
a row the engine would send, in the order authorizationParams, tokenParams,
refreshParams: \x1f <list>:<key>=<value>, further rows joined by \x1e,
the pairs sorted by key, then value, byte-wise). A row whose key names a
credential (client_assertion, assertion, an X-Api-Key or Authorization
header, the names an export blanks: core::vayu_ext::names_param_credential)
is written as <key>= with its value left out, because the key is returned as
cacheKey, stored as the cache row's primary key and can reach a log; a
rotated assertion therefore keeps the token it was cached under. Row order and
sendAs do not change the key; a config with no such row keys exactly as it
did before the lists existed. scope, audience and resource are not read, so a distinct
credentialsId (or an extra parameter row) is what separates two tokens that
differ only in those. The recipe is oauth::cache_key
(engine/include/vayu/http/oauth_client.hpp), and the app's
computeOAuth2CacheKey matches it byte for byte against the shared vectors in
engine/tests/oauth_client_test.cpp. Expiry uses a skew of min(45s, lifetime/2), so a 30s token is reused for 15s; a missing expires_in
means non-expiring. One refresh is in flight per cache key (#3344): however
many sends, runs and POST /oauth2/token calls find the same token expired at
once, the provider sees one grant_type=refresh_token post, and the others wait
for it, each under its own timeout and cancel, and answer with the row it wrote.
If that refresh fails (it timed out or was cancelled), a waiting call makes its
own rather than reporting the other call's error. A refresh whose refresh
token the provider refuses (invalid_grant or invalid_client; every other
refresh failure keeps the row, see POST /oauth2/token)
deletes the cached row only while the row still holds the refresh token
that was refused, so a rotating provider's invalid_grant for a spent token
never deletes the token that replaced it; an authorization_code user is not
sent back to sign in by a race. A refresh that issues no new refresh token
keeps the old one in the same write. A load run also refreshes its token during the run: a
watchdog re-acquires a header-placed, expiring token oauth2RefreshLeadMs
(default 60s) before it expires and writes the new one into this same cache row
(see Load Test Mode). A collection load run
does the same for the tokens its steps were planned with (#3199): one watchdog
per distinct cache key, however many steps send it, and every such step sends
the newest token from its first submission on. It is skipped - the token is
fetched once and reused for the whole run - for a query-placed token,
autoRefreshToken: false, a non-expiring token, an authorization_code grant
with no refresh token, and a send that carries its own Authorization header,
for which no token was fetched (#3202). That list is plan_oauth2_refresh's plus the header check
(engine/src/http/auth_resolver.cpp); the app's isMidRunRefreshable mirrors
all of it but the header case - change one, change both. A collection step is
also skipped when its auth waited on its scripts, and when it writes the token
under a different headerPrefix than the first step sharing its cache key
(plan_scenario_auth_refresh, engine/src/core/auth_refresh.cpp).
POST /oauth2/token¶
Acquire (or return a cached) token for an OAuth2Config. Supports the
client_credentials, password, and authorization_code grants; the
authorization_code grant requires an interactive code exchange (see below).
Request:
{
"config": { "grantType": "client_credentials", "accessTokenUrl": "https://idp/token",
"clientId": "...", "clientSecret": "...", "scope": "openid" },
"force": false,
"interactive": { "code": "...", "codeVerifier": "...", "redirectUri": "..." }
}
force: true bypasses the cache (refreshes via the refresh token when present,
else re-acquires). interactive is only used for the authorization_code grant,
and it always exchanges the code and overwrites the cached row, whatever force
says and whether the cached token is fresh, expired or refreshable (the old
refresh token is not carried over).
Client credentials sent in the Authorization: Basic header are form-encoded
before they are base64-encoded, as RFC 6749 section 2.3.1 specifies, so a secret
holding +, / or = travels as %2B, %2F, %3D. A provider that expects
them raw (as Postman and curl -u send them) needs credentialsPlacement:
"body", which puts client_id and client_secret in the form instead. The
default is basic_auth_header.
scope, audience and resource are sent in the form of a fresh grant when
set; a refresh sends none of them. Three optional config lists add parameters
of the user's own (issue #2536), each an array of {key, value, enabled,
sendAs?}: tokenParams on a fresh grant, refreshParams on a refresh, and
authorizationParams in the authorize URL's query (below). sendAs puts a
row in the form (body, the default), the token URL's query (url) or a
request header (header). A row is not sent when it is enabled: false, has
no string key, has an unknown sendAs, or is named like a parameter the
engine writes itself (grant_type, client_id, client_secret, code,
redirect_uri, code_verifier, refresh_token, username, password,
scope, state, code_challenge, code_challenge_method, response_type);
a body or url row naming a form parameter already written (an audience the
config sends) and a header row naming a header already set (Authorization,
Content-Type, Accept, case-insensitively) are skipped too, so the engine's
value wins and no name is sent twice. A malformed list or row is skipped, never
refused. Values are resolved with the rest of the config, by POST /compose or
after the pre-request script (see When it is applied), and
a {{data.*}} token in one is refused like one anywhere else in the config.
Response (200):
{
"cacheKey": "https://idp/token...",
"accessToken": "ya29...",
"tokenType": "Bearer",
"scope": "openid",
"expiresIn": 3600,
"createdAt": 1234567890000,
"expiresAt": 1234567893600,
"hasRefreshToken": true
}
expiresAt is null for a non-expiring token; scope is omitted when empty.
Errors carry an oauth2_* code: 400 invalid config, 401
oauth2_provider_error when the token endpoint answered without a token, 409
interactive authorization required, 502 network error, 504
oauth2_timeout when the token endpoint did not answer in time. A 401's
message always names the endpoint's status (#3201): a 4xx JSON answer, or an
RFC 6749 error under any status below 500, reads Token endpoint refused the
request (HTTP 400): invalid_client (bad secret); a 5xx, or a body nothing could
read, reads Token endpoint error (HTTP 503), with : unparseable response
when the body was neither JSON nor a form. The provider's reply rides inside
the error as providerStatus, providerError and providerErrorDescription,
each left out when absent. A body that is not JSON is read as the legacy
form-encoded token response only under an
application/x-www-form-urlencoded, text/plain or absent Content-Type, and
never when it opens with <, so a gateway's HTML page is not decoded as a
form. The
token request is bounded by the defaultTimeout setting (this route takes no
timeout of its own), and the bound covers the whole acquisition: a refresh
the provider rejects falls back to a fresh grant that gets only what the
refresh left (issue #2833).
Only a refusal of the refresh token itself clears the cached token: a refresh
answered 400 or 401 with an RFC 6749 error of invalid_grant or
invalid_client deletes the row (while it still holds that refresh token) and
falls back to a fresh grant, which for authorization_code is the 409 above.
Every other refresh failure keeps the row, so the next call refreshes again
(issue #3360). A refresh the endpoint could not answer - a 5xx, a 429, or a
reply carrying no RFC 6749 error, an unparseable body included - is a 502
oauth2_network_error whose message reads Token refresh failed: Token
endpoint error (HTTP 503): unparseable response, still carrying
providerStatus and the rest of the provider's reply. Any other refusal of a
refresh (invalid_scope, say) answers as the 401 oauth2_provider_error
above. A fresh grant's failure is unaffected: it is always that 401. The same bound holds for the token exchange of the
interactive flow below.
A token response nested past 100 levels is treated as unparseable (401
oauth2_provider_error, "unparseable response"), never cached (issue #2413).
GET /oauth2/token?key=<cacheKey>¶
Inspect the cached token for a key (used by the UI status row). Always 200.
Returns { "found": false } when no token is cached.
DELETE /oauth2/token?key=<cacheKey>¶
Clear a cached token. 200 { "deleted": true } (false if nothing was cached).
Interactive Authorization Code flow¶
For the authorization_code grant the engine owns PKCE (S256), the state
value, and the code exchange; the app only opens the browser. In loopback
mode the engine binds an ephemeral 127.0.0.1 listener; in embedded mode
(providers that reject loopback redirects) the app captures the redirect URL and
hands it back.
| Method / Path | Purpose |
|---|---|
POST /oauth2/authorize/start |
{config, mode?} → {attemptId, authorizeUrl, redirectUri, expiresAt} |
GET /oauth2/authorize/:attemptId |
Poll status → {state: "pending"\|"completed"\|"failed"\|"not_found", error?, cacheKey?}; reads only |
POST /oauth2/authorize/complete |
{attemptId, callbackUrl} → status (embedded mode) |
DELETE /oauth2/authorize/:attemptId |
Cancel → {cancelled: true} |
The authorize URL carries response_type, client_id, redirect_uri,
state, scope, audience, resource and the PKCE pair, then each
authorizationParams row under the rules above, whatever its sendAs (a
navigation has no body or headers); a row naming a parameter already in the URL
is skipped.
An attempt times out 5 minutes after it starts. expiresAt is that instant in
epoch milliseconds, the one deadline a client waits on. The engine enforces it
whether or not anyone polls: within a second of expiresAt the attempt is
failed with Authorization timed out and its loopback listener is closed, so an
abandoned attempt never keeps its port. On success the token is written to the
cache and cacheKey is returned. A settled result stays readable for 10 minutes
from the start, then the attempt answers not_found.
GET /oauth2/authorize/:attemptId reads only: polling never settles, fails or
tears down an attempt. An attempt past expiresAt reads as failed with
Authorization timed out from that instant on, and a callback or completion
arriving after it cannot change that.
At most 16 attempts may be unsettled at once, embedded ones included; the next
start is refused with 429 oauth2_authorize_limit_reached. A settled attempt
holds no listener and leaves the count.
Cancelling an attempt (DELETE), or the engine shutting down, cancels a token
exchange still in flight for it, the loopback callback's and an embedded POST
/oauth2/authorize/complete's alike: the callback's tab is told the exchange
failed, and the completion answers 404. A completion (the loopback callback and POST
/oauth2/authorize/complete alike) always exchanges its code and replaces any
token already cached under that key.
The loopback callback reads nothing before state, error included: a request
with a missing or wrong state answers 400 and the attempt keeps waiting, so
an IdP that omits state on its error redirect leaves the attempt pending until
it times out. A callback with the right state after expiresAt answers 410.
A loopback attempt settles once, and the first settlement wins: a later callback
with the right state answers 409 and changes nothing.
Local mock issuer¶
A built-in OAuth 2.0 issuer for developing and testing auth flows offline -
no real identity provider, so no 2FA prompts, provider rate limits or
"suspicious login" mail in the dev loop. Each issuer is an independent
127.0.0.1 listener serving /token and /authorize; point any OAuth 2.0
config's accessTokenUrl at the tokenUrl it returns.
It is not an IdP. JWKS/RS256, OIDC discovery documents, token introspection, consent screens and multi-tenant realms are deliberate non-goals.
| Method / Path | Purpose |
|---|---|
POST /mock-issuer/start |
Start one → {issuerId, issuerUrl, tokenUrl, authorizeUrl, signingKey} |
GET /mock-issuer |
List the running issuers |
PUT /mock-issuer/:id |
Update failureMode / slowMs / expiresInSeconds live |
POST /mock-issuer/:id/stop |
Stop one → {stopped: true} (404 if unknown) |
Start body (every field optional):
{
"port": 0,
"expiresInSeconds": 3600,
"claims": { "sub": "alice", "roles": ["admin"] },
"clients": [{ "clientId": "cid", "clientSecret": "s3cret" }],
"failureMode": "none",
"slowMs": 2000,
"issueRefreshTokens": true
}
port: 0 (the default) binds an ephemeral port; an explicit port another
engine listener already holds is a 500 with code mock_issuer_bind_failed
naming that listener, for the same SO_REUSEPORT
reason the inbox refuses one. clients empty accepts any
client id; with clients configured, an id must be one of them and, at /token,
one carrying a secret must present it (Basic header or body - both RFC 6749
§2.3.1 placements); /authorize checks the id only.
A field present with the wrong type or an out-of-range value is a 400
(mock_issuer_invalid_config) rather than a silent fallback to the default - a
mock issuer running with an expiry other than the one asked for would defeat the
purpose. At most 8 issuers run at once (429 mock_issuer_limit_reached).
The issuer's own endpoints:
POST /token-client_credentials,password,authorization_codeandrefresh_tokengrants,application/x-www-form-urlencodedas RFC 6749 §3.2 requires. Answers{access_token, token_type: "Bearer", expires_in, refresh_token?, scope?}. Authorization codes are single-use and expire after 5 minutes; a refresh grant rotates its token (the presented one is spent).GET /authorize- auto-approves and302s straight back toredirect_uriwithcodeandstate, so the interactive flow completes with zero human steps. PKCE is verified when acode_challengeis present;code_challenge_methodmust then beS256(plainis refused rather than quietly accepted). An unknown client or a missingredirect_urianswers in place rather than redirecting (RFC 6749 §4.1.2.1).
The access token is an HS256 JWT signed with the per-issuer signingKey the
start call returned - hand that key to the service under test as its shared
secret and it can verify the mock's tokens. The payload is the configured
claims plus iss, iat, exp and jti (these four always win, since they
describe the token being issued), with sub, client_id and scope filled in
only when the claims did not set them.
failureMode is what makes retry and error handling testable, and can be
flipped on a running issuer with the PUT:
| Mode | /token answers |
|---|---|
none |
Normally |
slow |
Normally, after slowMs (at once when the issuer stops first) |
server_error |
500 {"error": "temporarily_unavailable"} |
invalid_client |
401 {"error": "invalid_client"} |
Issuers bind 127.0.0.1 only - never configurable, because they mint bearer
tokens and the engine has no route auth. State is in-memory: a restart forgets
every issuer, and stopping one drops its codes and refresh tokens with it.
Execution¶
POST /compose¶
Compose a request without sending it: resolve {{variables}} and inherit
auth engine-side and return the execute-ready payload that POST /execute and
POST /runs accept unchanged (issue #226). Pure - no traffic, no run row -
which is what lets a client (e.g. MCP's allowlist gate) inspect the resolved
request before anything is sent. Composition is still the only place a payload
is composed; a payload that skips it is sent byte-for-byte as supplied. Since
issue #1008 the execution endpoints are not silent past that point either: a
name composition could not answer keeps its braces (issue #1009) instead of
resolving to "", and both POST /execute and a scenario step resolve it once
more, after the pre-request script and before the send, against whatever the
script just wrote. Since issue #2521 the same is true of every name a variable
scope does answer, in a request that a pre-request script (its own, a
folder's or the collection's) runs before: composition leaves it written and
lists it in deferredVariables, because the script may
change the value; a collection run's plan does the same in every step when any
element in it writes a variable. A value composition did substitute is finished text and is
never re-resolved - see POST /execute and
Scenario runs for what that changes.
Request - at least one of requestId / request is required:
{
"requestId": "req_1234567890", // Optional: compose the saved request
"request": { // Optional: an inline unresolved request
"method": "POST",
"url": "https://{{host}}/users",
"headers": [{ "name": "X-Token", "value": "{{token}}" }],
"body": { "mode": "json", "content": "{\"name\":\"{{name}}\"}" },
"auth": { "mode": "inherit" },
"elements": []
},
"collectionId": "col_1234567890", // Optional: chain scope for an inline request, echoed on the answer
"environmentId": "env_1234567890", // Optional: environment scope
"dataColumns": ["username", "city"], // Optional: bare names a bound row will substitute
"deferDynamicVariables": true // Optional: this payload is for a run that repeats it
}
-
dataColumns(issue #1007) names the columns of the data file a caller will bind a row from after this compose call - an array of column names, never values, since a plan is composed once and a row is bound per iteration. Every name it lists is left written as it stands, exactly as the reserved{{data.*}}namespace already is, for a later per-row bind to join -{{username}}behaves as{{data.username}}always has, deferred rather than resolved from a same-named variable. Absent ornullmeans no dataset: composition resolves exactly as it did before this field existed. Refused with400invalid_compose_requestwhen the field is present and not an array, or holds an entry that is not a string or is the empty string. Adata.-prefixed entry is accepted but redundant - the reserved namespace answers that spelling first regardless of whether it is also listed here, so either way it is deferred. See{{data.*}}puts the row into the request itself and D18 for the precedence this buys. -
deferDynamicVariables(issue #995) says this payload is being composed for a run, which will send it many times. A generator resolved here would be one value repeated by every iteration of every virtual user - the uniqueness{{$randomUUID}}is written for, lost exactly where concurrency makes collisions matter - so with the field true every name the dynamic table generates is left written as it stands, the way{{data.*}}and the identity names already are, and the run's executor generates a fresh value per occurrence immediately before each send. It also resolves an OAuth 2.0 config now, cache key included: a run acquires its token once, when it is planned, from the stored values (a script's write to an OAuth 2.0 variable has no effect under load), and every virtual user sends that one, so without the field (a Send) the config is left for the send to resolve after the pre-request script (see Authentication). Absent,nullorfalsecomposes exactly as it did before this field existed, which is what a Send, a preview and a script'sreplaceInwant: composed once, sent once. Refused with400invalid_compose_requestwhen present and not a boolean. Two limits worth knowing: an unknown{{$typo}}is unaffected (nothing would generate it either way, so it keeps its braces - issue #186), and a generator inside the auth block is generated here even when the field is true, becauseapply_authencodes a credential when the request is built and a token left for the bind would go out as base64 of its own text. That is a generator's case alone: a credential carrying a{{data.*}}or a{{$vu}}defers the whole build and is bound before the encoding (issue #1055), and one carrying a name no scope answered defers it until after the pre-request script (#2473, see Authentication), where a generator has nothing to wait for. A scenario plan's steps are composed with it internally, so a collection run needs no field at all (a sequential run's steps keep their OAuth 2.0 config for after the script, as a Send does; a collection load run's resolve it at planning). -
requestIdcomposes the stored request wholesale: URL, headers (every enabled row with a key, in row order, as{name, value}lines - a repeated name repeated, each in the spelling typed, issue #2466), body, auth (absent auth defaults toinherit), the resolvedelementslist (collection chain root→leaf, then the request's own, each stamped with its origin, disabled and blankscript.*entries dropped the same way - see Elements), the stored execution options (followRedirects/maxRedirects/httpVersion/verifySSL, always emitted; the request's owntimeout, emitted only when it states one, so a request that states none sends with thedefaultTimeoutsetting in force at the send, issue #2937), its Event stream setting asstream, always emitted (issue #3561: a caller that hands the payload toPOST /executegets202 {runId, eventsUrl}for a streaming request unless it statesstreamitself) and itsrequestName(the script sandbox reads it aspm.info.requestName; omitted when the row's name is empty). The request's own collection scopes resolution;collectionIdis only a fallback for a request without one. An unknown id is a definitive 404. requestis an inline unresolved request in thePOST /executebody shape. Given alongsiderequestId, its fields lay over the stored ones before resolution - how an override like "retarget this saved request at another URL" works. Given alone,collectionIdscopes the variable chain and theinheritwalk. Unknown scope ids degrade to an empty scope rather than erroring - composition works with no collection or environment at all. That rule is for the app and direct callers: the MCP server checks anenvironmentIdagainstGET /environmentsbefore composing and refuses one that names no environment (MCP).
deferredVariables¶
Composition decides from the composed elements (never from a flag the caller
sends) whether a pre-request script runs before the send: an enabled,
non-blank script.pre on the request, on a folder above it or on the
collection, after an inherit.disable entry and a disabled-by-id entry have
been applied and an inline elements array has been laid over the stored one.
A script.setup does not count - it runs once, before a collection run's first
step. When a pre-request script does run, every {{name}} that a variable
scope answers is left written in the URL, the :name path rows, header
names and values, body content and form-field strings, and the credentials of
an auth block that is not OAuth 2.0 (an OAuth 2.0 config defers too on a
Send and a sequential run, as Authentication describes), and the response lists the names
in deferredVariables: a sorted array of the names as written, omitted when
nothing was deferred. POST /execute and POST /runs resolve them after the
script, against the variable scopes as the script left them, and ignore the
member itself - it describes this answer, not the request, so a client that
posts the composed payload onward may leave it or drop it (the app and the MCP
server drop it). A request no pre-request script runs before is composed
exactly as it was before issue #2521: no deferredVariables. A collection
run's plan, which composes each step engine-side and returns nothing, defers
the same names in every step of a plan in which any element writes a variable
before some send, scripted or not (Scenario runs).
Four kinds of name resolve at composition whatever a script does, each exactly once:
- the
{{data.*}}namespace and the names listed indataColumns, which the per-iteration bind answers; - a
$name - a dynamic variable (generated once here, or by the run's executor underdeferDynamicVariables) or the iteration identity ({{$vu}},{{$iteration}}); - a name whose value, followed through the scopes, reaches a token the bind
owns (
{{user}}holding{{data.user}}), so the bind finds the token it needs; - a file path: the
srcof a form-data file part or a binary body file, which the later pass never resolves, so a script cannot choose which file is sent.
A name nothing defines stays written as it always did, and is not listed.
Deferral also moves refusals to the send. A header value or name that depends on
a deferred variable cannot be checked here, so the refusals described under
Errors below (unsendable_header, empty_header_name,
invalid_header_name, colliding_header_names) are made by the residual pass
at send time instead, in the same words and under the same codes: a buffered
POST /execute answers statusCode: 0 with the code as refusalCode, and a
streaming send answers a 400 carrying it.
collectionId on the answer¶
The answer names the collection whose chain this composition read, as
collectionId: the leaf, so a sub-folder's id rather than its root's. That is
the stored request's own collection for requestId, else the body's
collectionId, and the member is omitted when composition read no chain:
an inline request with no collectionId, or one naming a collection that does
not exist or is in the Trash (issue #3461). Like deferredVariables it is
composition's own answer, never taken from the input: a collectionId inside
request is dropped, so an inline request cannot claim a scope composition did
not read.
It is what lets an inline request keep its scope past composition. A request
composed by requestId, or sent with one linked (the app's Send does both),
carries the id onward and POST /execute reads the stored request's
collection again; an inline one that links no row (MCP's ad-hoc run_request
with a collectionId, a direct caller) has nothing else to name it, so without
the member the names deferred past its pre-request script would meet no
collection scope at the send, and the script would read an empty
pm.collectionVariables. POST /execute and POST /runs
read it as described under POST /execute. An engine older
than issue #3461 neither writes nor reads it, and ignores it in a body.
Query encoding¶
With disableUrlEncoding off, a URL is sent as Postman sends it, by every
writer: Send, a load or collection run, a streaming request, MCP and
pm.sendRequest put out one request line for one URL (issue #2465,
core::encode_url_as_postman in core/url_encoding.hpp, after
postman-url-encoder 3.0.8's toNodeUrl). Each component is percent-encoded
by its own Postman set, every one of which holds the C0 controls, space, DEL
and every byte above ~ (each UTF-8 byte):
- the path by
PATH_ENCODE_SET, which adds",<,>, backtick,{and}; - the query by
QUERY_ENCODE_SET, which adds",',<and>(a backtick, the braces and a backslash are not in it); - the fragment by
FRAGMENT_ENCODE_SET, which adds",<,>and backtick; - user info by
USERINFO_ENCODE_SET, the path set plus/ : ; = @ [ \ ] ^ |, with the last@ending it.
Two normalisations come with it: a backslash before the query becomes /, and
the host is lowercased and a non-ASCII one written by its punycode name
(Non-ASCII hosts). Leading whitespace is dropped, as
Postman's parser drops it. So GET http://H/a"b{c}?q='<x> goes to host h as
GET /a%22b%7Bc%7D?q=%27%3Cx%3E, and GET http://h/a b?q=é as
GET /a%20b?q=%C3%A9. % is in no set, so an escape such as %41 is sent as
typed and nothing is encoded twice: a pre-signed URL's signature is sent
unchanged, as is every byte no set holds (+, |, ^, [, ], !, '
outside the query). A {{token}} nothing answered is kept whole, where
Postman would encode its braces in the path. The rule is applied where every
driver takes its URL (wire_url) and at the end of composition, so
POST /compose answers the line that will be sent. Every check made beside
the transfer reads that same URL - the scheme rule, the
reserved-port refusal, the DNS pin and the
client-certificate match - so a leading space or a backslash cannot make the
typed text name another scheme, host or port than the one dialled:
localhost:9876/x with a leading space is refused as it is without one, and
https://h/ with one pins and matches port 443. With disableUrlEncoding
on the URL goes out exactly as typed (a non-ASCII host still by its punycode
name), and libcurl refuses a raw space: the send fails with status 0 and
error code INVALID_URL, and a message that names the space and the toggle
(Cannot send this request: the URL contains a space or control character; percent-encode it, or turn Send URL without encoding off),
derived from scanning the URL and not from libcurl's wording.
Where the engine itself writes a query pair into a URL, it uses Postman's
rule (issue #1771,
core::encode_query_component in core/query_encoding.hpp, pinned to the
app's Params table by engine/tests/fixtures/query-encoding-conformance.json),
read from postman-url-encoder 3.0.8's toNodeUrl over postman-collection's
QueryParam.unparse:
- Encoded as
%XX(uppercase hex): Postman'sQUERY_ENCODE_SET- the C0 controls, DEL, every byte above~(each UTF-8 byte), space,",#,',<and>- plus&in a key or a value and=in a key only (a value cannot split a pair, because a parser splits on the first=). - Everything else goes out as typed:
+,|,/,?,:,@,[,],{,}and%, so an escape already in the text is never encoded twice. A whole{{token}}is kept verbatim, with the text around it encoded. - The writers are an
apikeyauth within: "query"and an OAuth 2.0 token withtokenPlacement: "query"(a valuea|b+c=dgoes out as?k=a|b+c=d;key=is written even for an empty value), and the join of a Postman import's query rows into the stored URL (POST /import/parse), which writes a row with an empty value askey=and avalueless: truerow (Postman's"value": null) as a barekey. A request withdisableUrlEncodingwrites the pair as typed. - A value known only at send time is URL text, not a row: a
{{variable}}substituted into the URL (by composition, a data row's bind, or the residual pass after the pre-request script). Postman substitutes into the URL string, parses it again and then encodes it, so a value's&and=split pairs as they would typed, a?it brings into the head opens the query, and a#opens the fragment. Each component then encodes the value by its own Postman set (issue #2465): the query byQUERY_ENCODE_SETabove, alike in a key and a value (the&/=step of a row never applies); the path byPATH_ENCODE_SET(see Path variables), sohttp://h/users/{{name}}withname = "John Doe"sends/users/John%20Doe; the fragment byFRAGMENT_ENCODE_SET(the C0 controls, DEL, every byte above~, space,",<,>and backtick).GET {{base}}/?q={{term}}withterm = "a b#c"sends/?q=a%20b, with#cas the fragment (which is not sent), and?{{qs}}withqs = "a=1&b=2 c"sends?a=1&b=2%20c. Where a value lands is read left to right from the URL written so far, substituted values included: in the scheme and authority a/opens the path unless it follows a:or a/(so://is not a path), the first?opens the query,#opens the fragment. A layered value is resolved whole and encoded once. The scheme and the authority are never percent-encoded (the host is lowercased and written by its ASCII name, as above), so a{{base}}holdinghttps://x/p?k=a bhas its query part encoded and nothing else changed.disableUrlEncodingwrites every value as typed. - A pair a script adds with
pm.request.url.query.add,upsertorpm.request.url.addQueryParamsis a row and is written by the row rule above (scripting). - A
pm.sendRequestURL is encoded whole after its variables resolve, by the sameencode_url_as_postman, anddisableUrlEncodingdoes not apply to it (scripting). A script and Send write the same request line for every URL;tests/url_encoding_test.cpp(PostmanUrlEncodingAgreement) pins it. - OpenAPI, Insomnia and JMeter imports join with
encodeURIComponentinstead: the OpenAPI sync diff compares stored URLs against that form, and neither other source uses Postman's set.
URL schemes¶
Only http and https URLs are sent, on every send path: Send, a load or
collection run, a streaming request, History replay, MCP, pm.sendRequest, an
OAuth 2.0 token request, POST /import/fetch and the server-vitals monitor.
The scheme is read case-insensitively from the URL as it stands just before
the transfer - after composition, a data row's bind, the pre-request script
and the residual pass, and as the transfer is handed it
(Query encoding) - so a {{baseUrl}} that resolves to
file:///etc is refused like a typed one, and so is file:///etc with a
leading space. A refused send never reaches the network: status 0, error code
INVALID_URL, and the message
Cannot send this request: scheme 'file' is not supported - only http and https URLs can be sent,
naming the scheme as written. A pm.sendRequest gets the same code and
message as its callback's err.
A scheme is what libcurl reads as one: letters, digits, +, - and .
after a leading letter, followed by :/. A URL with no scheme is sent as
before, with the scheme libcurl guesses from the host - http for
localhost:8080/x or example.com/x. Every transfer handle is also held to
http,https (CURLOPT_PROTOCOLS_STR), which covers what the URL check cannot
see: a guessed scheme (ftp.example.com/x would be FTP). It fails as status
0 with error code INVALID_URL and libcurl's own message
(Protocol "ftp" is disabled), and nothing is read. A redirect's Location
never reaches the handle's allowlist: the engine follows redirects itself and
refuses a Location naming another scheme before making the hop, as status
0 with error code INVALID_URL and the message
Protocol "ftp" is disabled (in redirect), worded as libcurl worded it. A
Location that does not parse is INVALID_URL too, with The redirect target
URL could not be parsed: and the reason. The libcurl the engine links carries
every protocol curl builds by default, so the check and the option, not the
build, are what restrict each transfer to http and https.
A URL libcurl cannot parse is also status 0 with error code INVALID_URL.
When the URL the transfer was handed holds a space, a C0 control character or
DEL, which is how one reaches libcurl once disableUrlEncoding is on (or a
space sits in the host), the message says so instead of repeating libcurl's
component wording (URL rejected: Bad query): Cannot send this request: the
URL contains a space or control character; percent-encode it, or turn Send URL
without encoding off. The last clause is left out when the toggle is already
off, because it is no remedy. The scan is of the bytes, not of libcurl's text,
and a malformed URL with none of them keeps libcurl's message.
Non-ASCII hosts¶
A host written with non-ASCII characters is dialled by its ASCII (punycode)
name, on every send path: Send, a load or collection run, History replay, MCP,
pm.sendRequest, an OAuth 2.0 token request and GraphQL introspection.
https://bücher.example/ goes to xn--bcher-kva.example, which is the name
DNS resolves, the Host header and TLS SNI carry and the server certificate is
checked against. It is the name Postman sends to (url.domainToASCII, UTS #46
nontransitional processing): uppercase and full-width letters are mapped
(BÜCHER, ABC), and ß is kept, so faß.de is xn--fa-hia.de, not
fass.de. The stored URL keeps the spelling that was typed; a composed URL,
and so pm.request.url in the request's own scripts, carries the ASCII name,
because composition ends with the encoder the send uses
(Query encoding).
The conversion is ada's, the WHATWG URL library Node's domainToASCII is
built on, applied to the one URL every driver hands libcurl (which is built
without IDN support), so it matches Postman case for case, the IDNA hyphen
rules included: Node does not enforce them, so bücher-.example and
ab--cd.bücher.example convert. The conversion rewrites only the host, and an
ASCII host, an unresolved {{host}} included, is not converted; the rest of
the URL is written as Query encoding says. The raw request a response carries shows
the punycode name, because that is what was sent. Everything that compares a
host beside the transfer uses the same name - the cookie jar, the DNS cache,
the client-certificate registry, the proxy bypass list and a proxy URL - so a
cookie, certificate or bypass entry written with either spelling applies to
both.
A host with no ASCII name at all, such as xn--iñvalid.com (a punycode label
that does not decode) or one holding a space, is refused before anything is
sent: status 0, error code INVALID_URL, and a message naming the host.
Postman sends such a host as typed and the lookup fails; libcurl without IDN
would refuse it as "IDN support not present", which names the wrong cause.
Reserved local ports¶
No request the engine sends reaches Vayu itself: the engine's own port (the
--port it bound, 9876 by default) and the MCP server's port (9877) are
refused on this machine, on every send path - Send, a load or collection run, a
streaming request, History replay, MCP, pm.sendRequest, an OAuth 2.0 token
request, POST /import/fetch and the server-vitals monitor. The API's
gate admits a loopback request with no Origin, which
is exactly what the engine's own client sends, so without this a request in an
imported collection could read and write everything the API holds (issue
#2355).
"This machine" is any loopback spelling - 127.0.0.0/8 (127.1 and other
shorthand included), ::1, ::ffff:127.0.0.1, localhost in any case with
or without a trailing dot - and the unspecified 0.0.0.0 and ::, which
connect to the local host. Every other port on loopback is sent as usual. The
rule is applied twice:
- The URL the transfer is handed (Query encoding),
before anything is dialled: status
0, error codeINVALID_URL, and the messageCannot send this request: Vayu does not send requests to its own engine port 9876 on this machine - not when the URL names it, a redirect leads there or a host name resolves there(MCP port 9877for the other). This holds with a proxy configured too. - The address libcurl connected to, for every connection a transfer uses,
before a byte of the request is written. This is what refuses a redirect to
one of those ports and a name that resolves to loopback (
*.localhost, a DNS record pointing at127.0.0.1), with the same code and message. With a proxy in force the connected address is the proxy's, so this half cannot see the origin behind it; the URL check above still applies, and where a proxy you configured forwards to is your choice.
A $ref fetched through POST /import/fetch with reference: true runs a
wider rule on the same connected-address check: every loopback and link-local
peer is refused unless it is the source document's own host and port (issue
#2364, see
POST /import/fetch). It is added to the reserved ports,
so a source on one of them does not open it. The rule passes the proxy the
transport names and judges the reference's URL instead (issue
#2605); the reserved ports do
not: a proxy on one of them is still refused.
Path variables¶
A :name segment of the URL is answered by the request's own in: "path"
Params row of that key (issue #1764) - the inline request.params when the
inline request carries a params array, the stored row's otherwise (so an
inline url override still reads the stored rows). This runs before the URL's
own {{var}} pass, on the URL as written, and follows Postman's parse
(postman-url-encoder/parser, postman-collection's Url.parse /
Url.getPath):
- A segment is a path variable when it is a whole path segment - after the
authority, between
/and the next/,?,#or the end - that starts with:. The name runs to the first., and a suffix after it stays (:id.jsonsends7.json);:alone or:.xnames nothing. A{{variable}}token is opaque, a backslash is a/, and a port (host:8080), the query and the fragment are never read. - Only an enabled row answers; among several rows of one key the last
enabled one does. Postman's
VariableListanswers with the last row whatever itsdisabledflag, but Postman's editor has no toggle for a path variable; Vayu's does, and a disabled row answers nothing. A segment with no such row stays literal, which is also how every request stored before #1764 composes: a:xsegment with no path row is sent as written. - The value is
{{var}}-resolved exactly as the URL is, then written in place of:namepercent-encoded as Postman encodes it: Postman joins the raw value into the path (Url.getPath) and encodes the path withpostman-url-encoder'sPATH_ENCODE_SET, which is the C0 controls, DEL and every byte above it (UTF-8,%XXwith uppercase hex), space,",<,>,`,#,?,{and}- and nothing else. So a/in a value makes more segments (a b/csends/users/a%20b/c),@ : , ; = & + ! $ ' ( ) *and%go out as typed (user@x.com,12:30,100%, and an importeda%40b.comis not encoded twice), and a?or#is%3F/%23, so a value never ends the path. A whole{{token}}in the value is kept verbatim rather than encoded (see the next point). - A value that still holds a
{{token}}after that resolution - a bound data column, a deferred{{$guid}}, a name a pre-request script sets - is not written yet: its segment stays:namein the composedurl, and the row goes out in the composed payload'sparamsas{"key": "id", "value": "{{username}}", "in": "path"}, its value resolved as far as composition could. Whatever answers the token later - the per-iteration bind, or the residual pass after the pre-request script - writes the answer into the segment through the same encoding, so a data cella b?cgoes out as/users/a%20b%3Fc, never with a raw space and a query. A token nothing answers is written verbatim, as composition keeps one. Until then a pre-request script readspm.request.urlwith the:namestill in it. - A value that resolves to the empty string leaves the segment literal
(
:idgoes out as written), as Postman'sUrl.getPath(it writes only a non-empty string) and Insomnia'sapplyPathParametersToUrlboth do.
The composed payload's url is the substituted URL, and its params holds
exactly the path rows still waiting (absent when none is; an inline request's
own params is consumed, never echoed). /execute, /runs and a scenario
plan step (which is composed through this same path) read that params back
and write each waiting value into its :name segment once it is answered, at
the latest just before the send: a run with no residual pass writes it after
the bind, or once at the start for a load run that binds nothing (a raw
run naming an environmentId or requestId writes the values its start-of-run
pass answered there, the rest after the bind). A caller
posting its own params path rows to /execute or /runs gets the same
writing.
What gets resolved: the URL, header keys and values, body content and
fields, and every string inside the winning auth block - after inherit is
walked (leaf→root; an explicit noauth terminates the walk, none is stepped
over) and before any OAuth 2.0 cache key is derived from the config: the key is
always computed from the resolved config, here for a run, after the
pre-request script for a Send (below). A request no pre-request script runs
before is resolved here, once. One that has one keeps what the script may
change as {{name}}, as deferredVariables describes.
Script text is never interpolated - a {{...}} in a script is user
JavaScript. Resolution semantics (precedence, unknown names, dynamic
variables, the D17 malformed-data rules) are specified in
variable-resolution and pinned by the shared
conformance fixture (engine/tests/fixtures/variable-resolution-conformance.json).
Response: 200 with the composed payload - the POST /execute body shape,
with requestId / environmentId echoed so the result can be POSTed onward
unchanged, the collectionId whose chain it
read, and deferredVariables when a pre-request script defers names (above). An auth that resolves to "send nothing" is an absent auth field.
headers always comes back as the line array (issue #2466), whichever shape an
inline request used, so a repeated header survives compose to execute; it is
absent when there are no lines.
Errors use the engine's single nested shape (see the top of this page), with specific codes:
404{"error": {"code": "request_not_found", "message": "..."}}- unknownrequestId.400{"error": {"code": "invalid_compose_request", "message": "..."}}- malformed JSON, neitherrequestIdnorrequest, or a field of the wrong type.400{"error": {"code": "unsendable_header", "message": "..."}}- a variable substituted into a header name or value, or into a credential the engine writes into a header line as it stands (a bearer token, an api key sent in a header), carries a byte no header line can hold. Basic auth's pair and an api key sent in the query are encoded before they reach the wire, and an OAuth 2.0 config is not a header, so a variable in those composes unchanged. This is the one payload composition rejects over a value rather than over its shape, and it is deliberate: a header line ends at CRLF and has no escape for it, sook\r\nX-Admin: truearriving from an environment variable does not sit in the header - it ends the line and makes the remainder a header nobody wrote. The message names the variable, because composition is the last layer that knows which one carried the byte. A NUL is refused with it: the engine spells a headerkey + ": " + valueforcurl_slist_append, which reads to the first NUL, so the rest of the line would go out missing rather than refused. The same bytes remain ordinary text in a URL, a body and a form field's value, which compose unchanged. For a request a pre-request script runs before, a variable written into a header or a header-line credential is not substituted here (seedeferredVariables), so the same refusal, naming the variable, is made after the script:statusCode: 0andrefusalCode: "unsendable_header"on a buffered send, a400with that code on a streaming one. A header row is refused with nothing rewritten first.
A header carrying either byte from any other origin - a script's assignment
to pm.request.headers, a credential typed with the byte in it, an import,
a payload posted straight to POST /execute - is refused one step later,
before any transfer starts: the response carries statusCode: 0 and an
errorCode of INTERNAL_ERROR whose message names the header instead of a
variable. The
same refusal covers a multipart part's field name, declared filename and
per-part content type, which libcurl writes into that part's own header block.
A bound {{data.column}} is refused earlier still, at bind time, naming the
column and the row (see Scenario runs).
- 400 {"error": {"code": "colliding_header_names", "message": "..."}} - two
header names written differently resolved to one, so the request would send
that header twice where its rows show two different names.
{{tenant_header}}: acme beside a literal X-Tenant: legacy is two
X-Tenant lines once the variable answers X-Tenant, and no row says so.
Names are compared without case, so a {{h}} resolving to
authorization refuses beside an Authorization the caller typed. The
message names both spellings as written, never the name they produced (a
variable can hold a secret); nothing is repaired, for the reason a forged header is refused rather than stripped.
Only a collision resolution produced is refused. Two names the caller
wrote alike - X-Dup and x-dup typed on two rows, or one {{h}} typed
twice - are a repeated header they can see, and every one of those lines is
sent, in order (issue #2466) - the same distinction the bind-time refusal
draws (see Scenario runs). The execute-time residual pass
refuses the same collision in the same words, since it resolves names the same way:
a buffered send answers statusCode: 0 with an errorCode of
INTERNAL_ERROR carrying the message and this code as refusalCode, exactly
as the pre-send gate answers its own refusals,
while a streaming send - which has not answered yet - is a 400 with this
same code and fails its run row. A script's own pm.sendRequest refuses it
as well, with the call named in front of the same wording, because it too
resolves header names (issue #1067).
- 400 {"error": {"code": "empty_header_name", "message": "..."}} - a header
name resolved to the empty string, so the line would go out under no name at
all. {{blank}}: acme with blank holding "" is not a header the caller
can see: the name is empty, and what libcurl is handed is the line
": acme". A name of nothing but spaces and tabs counts as empty: it is
trimmed to nothing first (see invalid_header_name, below). Nothing further
down refuses it - the pre-send gate
reads a header's text for the bytes that end a line early, and an absent name
ends nothing - so composition is where it is caught. The message names the
name as written, which is all there is to name; what it produced is nothing.
Refused however the name got there, unlike the collision above. A collision
has to be one resolution produced, because two names the caller typed are two
entries they can see; a name that is not there is nothing to see whoever wrote
it. Both flattenings that feed composition drop such a row before it arrives -
a stored request's headers and the app's - so what this catches beyond a
produced name is a payload built by hand. The execute-time residual pass
refuses it in the same words and under this same code, in each of the two
shapes it answers a refusal in (above), and for this rule it reads every
header name rather than only the ones still holding a token (issue #1095) - so
a name a pre-request script has just emptied and an empty key posted straight
to POST /execute are refused there as well. The collision rule keeps the
narrower reach and loses nothing by it: a request that arrives already
resolved cannot carry a collision, two names that are already equal being
already one key. pm.sendRequest has refused it since its own header names
began resolving, with the call named in front of the same wording, and a data
row that binds a name away is refused at bind time with the row in front of it
(see Scenario runs).
- 400 {"error": {"code": "invalid_header_name", "message": "..."}} - a
header name that is not an RFC 9110 token once the spaces and tabs around
it are trimmed (issue #2467): X Bad (an interior space), X:Bad (a colon),
X-é (a byte outside ASCII). The message quotes the name as written -
{{h}}, not what the variable resolved to, which can be a secret - and says
which character cannot appear in one. Nothing is rewritten into a different
header: the trim below is for padding, which has one reading, and this
refusal is for what has none. The same refusal, under the same code, answers
a headers name posted to POST /execute or POST /runs and the
execute-time residual pass (a buffered send answers statusCode: 0 with
INTERNAL_ERROR, a streaming send a 400, as above), which is where a name
a pre-request script defined, or one a script's variable completes, is
judged; a script's pm.sendRequest and a data cell bound into a name refuse
the same way, with the call or the row in front of the wording. A {{token}}
nothing answered is not judged, since like every unanswered token it is sent
as written, but the text around it is: X-{{a}}-b passes, X Bad {{x}} and
Evil: injected{{ (a {{ that closes no token is ordinary text) are refused,
quoted as written.
Header names are trimmed, then checked. A name loses the spaces and tabs
(SP and HTAB, nothing else) at either end before it is checked or sent,
wherever it enters: a stored
request's header rows, a composed or resolved name, and the headers of
POST /execute and POST /runs. Authorization therefore goes out as
Authorization, not as the line Authorization : Bearer x with a space before
its colon. A row whose key is only padding is no row, as an empty key always
was. A value is not trimmed. Two lines written X-A and X-A are a repeat
the caller typed, sent as two lines, not a collision. In the object form of
headers two keys that differ only by padding or case fold to one line (the
last value wins), because an object has one slot per key; the array form
sends both.
POST /execute¶
Execute a single HTTP request (Design Mode). Returns immediate response with test results.
A body nested deeper than 128 levels in any field answers 400 request body
is nested deeper than 128 levels (code bad_request) before anything is
recorded or sent (issue #2417). The one exception is a data cell, held to its
own bound of 100 below.
The request's auth (see Authentication) is resolved before
the pre-request script runs, so pm.request reflects the real outgoing headers -
unless a credential still holds a name that waits for that script (one compose
could not answer, or any name of a request a pre-request script runs before),
when it is applied after that script instead (#2473, #2521).
If a non-interactive OAuth 2.0 token cannot be obtained, the engine still returns
200 but the body carries statusCode: 0, an errorCode of AUTH_REQUIRED
(interactive sign-in needed) or AUTH_FAILED, and an authErrorCode hint. The
hint is the same whether the token was sought at the build or, for a config that
waited for the script, after it.
A name still written after compose is resolved after the pre-request script
and before the send (issues #1008 and #2521). Composition still runs first and
is still the only place a payload is composed. Two kinds of name reach this
pass: an unknown ordinary {{name}}, which keeps its braces at compose time
instead of becoming "" (issue #1009), and, in a request that a pre-request
script (its own, a folder's or the collection's) runs before, every name a
scope answers, which compose leaves written and lists in
deferredVariables. Either is resolved here against the
variable scopes as the pre-request script left them, and there is no flag for
the caller to set: the braces in the payload are the whole signal. This is what
makes the canonical imported auth pattern work: a pre-request script does
pm.environment.set("token", …) and the same send's Authorization: Bearer
{{token}} carries the fresh value - on every run, not only the first, which is
Postman's order - rather than the previous run's token or "". In a
pre-request script, pm.request.url and pm.request.headers therefore still
hold the {{token}} as written, and resolve after the script ends. A
credential that waited (above) is applied once this
pass has answered, against the same scopes, so a basic pair carries the value a
script set rather than base64 of its token. It resolves the same fields
composition does - the URL,
header names and values, body content, and the five strings a form field
carries, plus the value of a :name path variable composition left waiting
(written into its segment, encoded, as the pass ends; see
Path variables) - by the same resolver and the same rules (scope precedence, nested
resolution, cycles, the 8-level bound); a value composition already
substituted is finished text and is not touched again. {{data.column}} is
left alone here too - the data namespace is bound per iteration by whoever owns
the row. A request skipped by pm.execution.skipRequest() resolves nothing,
having nothing left to send. A header value or name this pass resolves is
checked by the rules compose applies, before anything is rewritten, and a
refusal is answered with statusCode: 0, the sentence in errorMessage and the
rule's code in refusalCode (unsendable_header, empty_header_name,
invalid_header_name, colliding_header_names, and the two codes of
targetPolicy below); a streaming send answers a 400 under
the same code. The member is absent on any other answer. A preview, a tab title,
the unresolved-token painting and "Copy as cURL" show what compose
returned, so for a scripted request a preview shows {{token}} where the wire
will carry the value the script set (the Code section says so). A load run
runs this pass per submission only where it has one (a collection load run's
steps, a single-request run that declares requestElements), and under load it
never refuses: see Authentication and
Scenario load runs.
Request:
{
"method": "POST",
"url": "https://api.example.com/users",
"headers": [ // Optional, the lines to send, in order - see below
{ "name": "Content-Type", "value": "application/json" }
],
"body": {
"mode": "json",
"content": "{\"name\":\"John\"}"
},
"requestId": "req_1234567890", // Optional, links to saved request
"requestName": "Create user", // Optional, read by scripts as pm.info.requestName
"environmentId": "env_1234567890", // Optional, uses environment variables
"collectionId": "col_1234567890", // Optional, the collection scope of a request no row names - see below
"timeout": 30000, // Optional, ms, 1-86400000 - see below
"elements": [ // Optional, typed behaviours - see Elements. The only
// script source; preRequestScript/postRequestScript(s)/tests
// are refused (400, naming "elements"), and so is a list
// the element registry refuses - see below
{ "kind": "script.post", "config": { "script":
"pm.test('Status is 200', () => pm.expect(pm.response.code).to.equal(200));" } }
],
"allowScriptRequests": false, // Optional, default false - see below
"followRedirects": true, // Optional, default true
"maxRedirects": 10, // Optional, default 10
"verifySSL": true, // Optional, default true - stored per request and
// settable in the request builder's Settings tab
"httpVersion": "auto", // Optional: "auto" | "http1.1" | "http2", default "auto"
"transient": false, // Optional, default false - see below
"persistVariables": true, // Optional, default true - see below
"includeParsedBody": true, // Optional, default true - see below
"origin": { "kind": "app" }, // Optional, who started the run - see below
"targetPolicy": { // Optional, the hosts this send may reach - see below
"allowAll": false, "allowedHosts": ["api.example.com"]
},
"stream": false, // Optional, default false - see below
"maxStreamDurationMs": 600000, // Optional, streaming only - see below
"maxStreamEvents": 100000, // Optional, streaming only - see below
"data": { "id": "7" }, // Optional, one data row - see below
"disabledDefaultHeaders": [], // Optional, headers Vayu adds that this send refuses
"disableCookies": false, // Optional, default false - stored per request, see below
"disabledSystemHeaders": [], // Optional, default [] - stored per request, see below
"disableUrlEncoding": false, // Optional, default false - stored per request, see below
"bodyModeHeaders": ["Content-Type"] // Optional, which `headers` the body mode wrote - see below
}
headers is the request's header lines, in send order (issue #2466): an
array of {"name", "value"} objects, each sent as its own line in the order
given and in its own spelling, so a name may repeat (Link, Forwarded, two
Accept rows, X-Dup beside x-dup) and the authored order is the wire
order. The older object form ({"Accept": "application/json"}) is still
accepted and behaves as it always did: one line per key, so it cannot repeat a
name. A line without a string name and a string value, or headers of any
other type, is a 400. A name is trimmed of the spaces and tabs around it
and what is left must be an RFC 9110 token: one that is not (X Bad, X:Bad,
X-é) is a 400 with code invalid_header_name quoting the name, in either
shape and before any run row exists (a name still holding a {{token}} waits
for the residual pass below, which judges it once resolved); a name of only
padding is the empty name the residual pass refuses (empty_header_name). The
refusal and the trim are the ones POST /compose documents.
POST /runs reads the same field the same way, and refuses a single-request
run's bad name with the same 400 before the run row exists. What
the engine adds (an auth header, the body-implied Content-Type, the
defaults) is added only under a name no line
already carries, compared without case; a typed Authorization sent twice is
sent twice and auth adds none.
timeout is the whole-transfer deadline in milliseconds (issue #1917), held
to 1-86400000 and defaulting to the defaultTimeout setting when absent or
null. A stored request's own timeout (issue #2937) reaches this field the
same way: POST /compose by requestId writes it into the
payload only when the request states one, so a composed send takes the inline
overlay's timeout, else the stored request's, else the setting. A number outside that range, or a value that is not a number, is a 400
naming 'timeout' before any run row exists and with nothing sent: libcurl
reads 0 as "no timeout", and a negative value is a rejected option the
transfer then runs without. POST /runs holds the same bound (see its
run config table). Connecting (TCP and the TLS handshake) is
additionally capped at 30 seconds (issue #2835), so a timeout above that does
not extend how long a dead target is waited on. A streaming send does not apply
it to the transfer (see stream below) but refuses a malformed one all the
same. In a
load run the latency histograms hold one hour at most (issue #2790): a
completion longer than that, a timeout above 3600000 that ran out, is counted
at one hour, so a percentile or max it reaches reads about 3600000 ms (within
0.1%) rather than the true duration, and the sample is never left out.
The same deadline bounds the OAuth 2.0 token request an auth block makes
(issue #2833), a refresh, the wait for another call's refresh of the same
token, and the fresh grant a rejected refresh falls back to counted together: a token endpoint that does not answer within it fails the
send as AUTH_FAILED with authErrorCode oauth2_timeout, and the request
itself is never sent. It is also the default timeout of every pm.sendRequest
the send's scripts make, buffered or streamed; a call's own timeout option
replaces it, and the script's remaining budget can only lower either
(Scripting).
requestId, environmentId and collectionId must be strings (issue
1917, collectionId since #3461): an id of any other JSON type¶
("requestId": 7) is a 400 naming the field - 'requestId' must be a string
(got number) - before any run row exists. Absent and null mean no link.
POST /runs reads the same three fields under the same rule.
The collection scope of a send is decided once (issue #3461): the
collection of the request row requestId names, when there is a live one, and
otherwise collectionId, the member POST /compose
writes on an inline request's answer - composition's own precedence, so a
request field and a script read one chain. Its chain is what the pre-request
and post-request scripts read and write (pm.collectionVariables answers the
leaf's names and its ancestors', and a set() is stored on the leaf alone,
never on an ancestor), what the names deferred past the pre-request script
resolve against, and what the run's configSnapshot is masked against. An id
naming nothing, unknown or in the Trash since composition, is an empty
collection scope and the send goes out, never a refusal, as composition treats
it. The field rides into configSnapshot with the rest of the payload, which
is how a stored run records the scope it sent under.
disabledDefaultHeaders refuses what the engine would add (issue #1229).
The engine adds a small declared set to every request that does not name it -
see Default request headers - and a testing tool
has to be able to send exactly the request that was written, including one with
no User-Agent at all. Names are matched case-insensitively; the field is
accepted on POST /execute and POST /runs alike. A value that is not an
array of header names is a 400 naming the field, because a malformed opt-out
would otherwise read as one that did nothing. A name matching no current
default is accepted and does nothing: config can switch a default off between
the moment a client read the declared set and the moment it sends. A name is
checked as a header token only, so User-Agent, Accept-Encoding and
Content-Type are all accepted (until issue #1765 the correlation-id
validator refused those three with a 400).
disableCookies / disabledSystemHeaders / disableUrlEncoding are the
request's stored Postman protocol settings (issue #1765; see
POST /requests). POST /compose always emits them from the
stored row and the app always sends them, on POST /execute and
POST /runs alike, because each defaults to off: an omitted true would send
the jar, the header or the encoding the user turned off. disabledSystemHeaders
is unioned with disabledDefaultHeaders, which stays the per-send,
never-stored opt-out, and is refused on the same shape rules. disableCookies
takes the jar off the buffered and the streaming send and off a scenario load
run's per-virtual-user session (the step neither sends nor updates it); a
single-request load run never tracks cookies at all.
bodyModeHeaders names the headers the body mode wrote (issue #1765): the
header names whose last row carried "source": "body-mode", compared without
case. A headers line has no room for the marker, so POST /compose emits this
list from a stored request's rows (only when it names something) and the app sends it
beside an inline request's headers; inline headers replace the stored ones,
so the stored list is dropped with them. A name in it that
disabledSystemHeaders or disabledDefaultHeaders refuses is left off the
wire, as Postman leaves off the body's Content-Type as a system header; a name
not in it is the user's and is sent. A value that is not an array of strings
is a 400.
stream consumes a text/event-stream response live (issue #573) instead
of buffering it. It changes the execution model, so it is declared rather than
detected: the engine creates the run row, hands the transfer to a managed
consumer worker, and answers 202 at once with the run and the URL its
events arrive on. Nothing about a non-streaming send changes.
The worker parses SSE frames into a bounded in-memory ring that
GET /runs/:runId/events relays, and writes a bounded
events node into the run's stored trace when the stream ends, so History
restores the timeline. The cookie warnings a buffered send answers with
(issue #3315) are written to the same stored trace, at its top level; the
202 carries none.
What the reply's bytes become depends on the final response's Content-Type
(issue #3238), read per redirect hop, compared without case and without its
parameters. A text/event-stream reply's bytes are its events and the stored
response.body stays empty. Any other reply (a JSON 404, NDJSON, chunked
text) also keeps its bytes as response.body, up to
maxDesignResponseBodyBytes, the bound a buffered send reads under. Past it
the body is a prefix and the trace says so with bodyCapped: true, as on a
buffered send; the stream itself still ends only by the rules below. Such a
reply is still fed to the SSE parser, so a server that streams SSE under the
wrong type still delivers its events. Either way the stored response
carries bodyBytes, the body bytes the server delivered, whatever was kept:
the relay carries no body, so the stored trace is where it lands.
A UTF-8 byte-order mark at the very start of the stream is dropped, as the EventSource specification requires (issue #1917); without that the first line's field name would carry the mark and the first event would be lost. One mark is dropped, however its three bytes are split across reads, and only at the start.
Every stream ends, and the run says why. Seven terminations, never "the timeout happened to fire":
| Reason | What happened |
|---|---|
completed |
The server closed the stream |
stopped |
POST /runs/:runId/stop |
shutdown |
The engine shut down under the stream (POST /shutdown or a signal), which no user asked for (#3342). The run ends stopped, as a load run still sending does; this reason is what tells it from a user's Stop |
maxStreamEvents |
The event cap was reached; the list ends exactly at the cap, however the server packed events into writes (an unterminated event behind the last one is not flushed) |
maxStreamDurationMs |
The duration cap elapsed, counted from the first hop of a redirect chain |
idleTimeout |
Nothing arrived for sseIdleTimeoutMs on a made connection; a header line counts as arriving, and each redirect hop's own connect is bounded by the connect deadline below, not counted as silence. The stream ends within a couple of seconds of the setting (the engine checks about once a second) |
error |
The transfer failed (a refused or timed-out connect, TLS, a protocol error, a redirect the chain refused); the run ends failed with the error fields set. Also what an end nobody recorded reads as, which the engine logs, since it is not known to be a completion |
The whole-transfer timeout is deliberately not applied to a stream - it
would kill a healthy one mid-flight. Two deadlines apply instead: connecting
(TCP and the TLS handshake, on every redirect hop) is bounded by the smaller of timeout and 30
seconds (issue #2835), and once connected the idle one bounds silence; the two
caps above are what bound a stream that talks forever. A connect that runs out
ends the stream as error with errorCode TIMEOUT, as a refused connection
does, never as idleTimeout. maxStreamDurationMs
(1000–86400000) and maxStreamEvents (1–10000000) override the configured
defaults per request; sending either without "stream": true is a 400,
since a cap that quietly did not apply is worse than no cap.
Refused with a 400 rather than silently reinterpreted:
- a non-boolean
stream('stream' must be a boolean); "stream": truewith"transient": true- a stream is its run row: the row is whateventsUrlnames, what carries the status, and what a stop finds, and a transient execution creates none.
Scripts run on a streaming request (issue #575), and were refused until they
did. The pre-request script runs before the transfer starts, exactly as on a
buffered send, so its pm.request edits reach the wire. The post-request script
runs once, after the stream has terminated, and reads the bounded stored
list as pm.response.events with pm.response.totalEvents and
pm.response.eventsTruncated beside it - a script runs to completion, its
timers included, before anything is reported, so a live per-event callback is
not a feature that was skipped but one the runtime cannot have. See
Scripting.
Because the route has already answered 202, a streaming run's script output
has nowhere to be returned: the trace's scripts node is the only route it
takes. That node is not a streaming feature - every design send stores it
(issue #725), with the same four keys the buffered response body carries
(testResults, consoleLogs, preScriptError, postScriptError). One engine
object fills both, so a live pane and a restored one cannot disagree. A run
whose scripts said nothing stores no node at all.
Tuning: sseMaxRetainedEvents, sseMaxEventBytes, sseMaxStoredEvents,
sseMaxStreamDurationMs, sseMaxStreamEvents and sseIdleTimeoutMs (see
GET /config).
transient runs the request without recording it (issue #382). The
execution is otherwise identical - same composition, the cookie jar named by
environmentId, the same scripts, the same response body - but the engine
creates no run row: nothing appears in GET /runs, no result trace is
written, and the count-based retention prune does not run, so no existing run
is evicted. Because the trace is where the post-auth request headers would have
landed, a transient execution is also the only way to send with resolved
credentials and leave none of them on disk.
Absent and null both mean false; a present non-boolean is a 400
('transient' must be a boolean) rather than a silent false, because a
caller that asked for privacy must not be quietly refused it. The flag is
not valid on POST /runs - a load or scenario run is the row it creates
(the run id is the endpoint's return value), so sending it there is a 400
with errorCode: "invalid_run_config".
The one caller today is the app's GraphQL schema introspection
(lib/graphql/introspect.ts), a background fetch the user never made. MCP's
run_request deliberately does not set it: an agent's runs belong in
History like anyone else's, and the tool builds its payload from named
arguments, so an agent cannot supply the flag either.
origin says who started the run (#1817):
{"kind": "app" | "mcp" | "other", "client": "<name>"}, stored on the run row
(runs.origin / runs.origin_client, see
the runs table) and returned on every run shape -
GET /runs rows, GET /runs/:runId and
PUT /runs/:runId/baseline - as
origin: {kind, client}. It is client-asserted metadata, not identity: any
caller can claim any kind and nothing authorises on it; History reads it to
say which runs an agent started. The app sends {"kind": "app"}; the MCP
server sends {"kind": "mcp", "client": "<clientInfo.name>"} with the name its
client gave in the initialize handshake.
- Absent or
nullstoresotherwith no client.otheris also what every run recorded before the field existed reads as. clientis kept formcponly and dropped forappandother. It is trimmed of whitespace and cut to 128 characters (on a character boundary, never inside a UTF-8 sequence); one that is empty after trimming stores no client. Otherwise it is stored exactly as sent: turning an identifier into a product name is the client's job, so a new MCP client needs no engine change.- A non-object
origin, akindoutside the three (a missing one included) or a non-stringclientis a 400 naming the field, for example'origin.kind' must be one of app, mcp, other, before any run row exists and with nothing sent. Atransientsend reads and validates it the same way and stores nothing. - The object is kept out of
config_snapshot: the row's two columns are its one record.
POST /runs takes the same field under the same rules.
targetPolicy holds the send to the hosts its caller allows (#2521):
{"allowAll": boolean, "allowedHosts": string[]}, both members optional. The
MCP server checks its allowlist against the composed URL, but a pre-request
script can assign pm.request.url or set the variable a deferred {{host}}
resolves from, so the caller also hands the engine the rule and the engine
applies it to what it is about to send. It is the caller's session rule,
changing per request, and rides on the payload rather than in config.
- What is judged. The host of the URL as it will be dialled (the wire URL,
after the pre-request script, the residual pass and the URL encoding), and,
before any token is read from the cache or fetched, the host of an OAuth 2.0
config's
accessTokenUrlandrefreshTokenUrl(whichever are set, both whether or not this send would reach the refresh one, so the answer does not depend on what the cache holds), each also as the token request will dial it (#3162), sohttp://evil.example\@idp.example/tokenis judged asevil.example. A script can set anaccessTokenUrlas easily as the request's URL, and the token request carries the client secret; a refused target fetches no token. - The match is the MCP server's: the hostname as a WHATWG URL parser
reports it (no port; an IP literal in its canonical spelling, an
internationalised name by its punycode form), compared exactly with each
allowedHostsentry once that is trimmed and lower-cased. There is no wildcard.allowAll: truepasses any host that can be determined. A host that cannot be - an empty one, or one still holding a{{template}}nothing answered - is refused whatever the policy says.{}allows no host. - A refusal never reaches the network. A buffered send answers
statusCode: 0, anerrorCodeofINVALID_URL, the sentence naming the host inerrorMessage, andrefusalCodetarget_not_allowed(a host the policy does not list) ortarget_host_unknown(no determinable host); an OAuth 2.0 token endpoint it refuses at the build is answered the same way, and not as an auth failure. A streaming send answers a400carrying the same code before its stream opens. - A malformed policy - not an object, an
allowAllthat is not a boolean, anallowedHoststhat is not an array of strings, or any other member (so a misspeltallowedHostcannot quietly allow nothing) - is a400with codeinvalid_target_policy, before anything is recorded or sent. Absent ornull, a send reaches whatever its request names. - It is never stored. The top-level member is dropped from a run's
config_snapshot(asoriginis), and a run holds it in memory only. - What it does not cover: the hops of a redirect a server answers with, and
the requests a script makes with
pm.sendRequest.
POST /runs takes the same field; see there for how a collection
or load run is held to it.
data binds one row to this send (issue #601). It is the single-send half
of a run's scenario.data: every {{data.column}} in the URL, the header names
and values, the body and both halves of every form field is substituted against
it, and both scripts read it as pm.iterationData with pm.info.iteration 0
and pm.info.iterationCount 1 - the send is row 0 of 1. Without the field
nothing changes: {{data.*}} goes out written as it stands and
pm.iterationData is undefined.
The row's own keys are also its bound bare names (issue #1007): the send
derives its dataColumns set from data's keys itself, so a bare
{{username}} binds from the row exactly as {{data.username}} does, at the
same precedence D18
gives it. A bare name the row does not carry is not deferred in the first
place - it is an ordinary {{name}}, resolved from the scopes at compose time
or, if nothing there answers either, by the residual pass after the
pre-request script (issue #1008).
An object of name/value pairs, never the array a run sends - one row. The
row is bounded by maxScenarioDataBytes (the same setting a run's whole set is
measured against) and composes freely with transient and stream: a streaming
send binds the row before the transfer opens, so the URL and headers it opens
with are the bound ones.
Refused with a 400, before any run row exists and with nothing sent:
| What | Message |
|---|---|
data is not an object |
'data' must be an object of name/value pairs (got array). A single send binds one row; a set of rows is a collection run. |
| over the byte cap | 'data' is N bytes, over the limit of M (raise the 'maxScenarioDataBytes' setting to allow more) |
| a column nested deeper than 100 levels | 'data' column 'name' is nested deeper than 100 levels - refused before the row is measured (issue #2362); a column nested exactly 100 levels is accepted |
| a token names a column the row lacks | the binder's own sentence, naming the token, the row and the row's columns |
a null cell, a header collision, a header name bound to nothing, an unwritable XML placement |
the binder's own sentence - identical to a run's, see Scenario runs |
an OAuth 2.0 config carries a {{data.*}} token |
Auth credentials carry {{data.client}} in an OAuth 2.0 configuration, and no row can reach it: ... |
Credentials bind here too (issue #642). A {{data.user}} in a basic-auth
username, a bearer token or an api key is substituted from the row like any
other field, and it is bound before the credentials are encoded - so basic
auth base64s the row's values, and an api key in the query is encoded by the
query rule after the substitution rather than before. This is the same deferral a
collection run performs per iteration (issue #591): the credentials are parsed
and kept typed, the request is built without resolving them, and the auth is
applied once the row has reached it.
OAuth 2.0 is the one mode a row cannot reach, and it is refused by name rather than sent wrong. Its token is acquired against the token endpoint instead of being written into the request, so there is no moment at which a bind could happen - exactly the reason a scenario run refuses the same config. Use a static credential there, or move the data token into the request itself.
requestName is script identity, not an HTTP field - it never reaches the
wire. The scripts read it as pm.info.requestName (with requestId as
pm.info.requestId); a client sends it because Send executes editor state,
which may be unsaved and therefore have a name no stored row carries. Absent,
the engine falls back to the name of the row named by requestId, so linking
an id is enough. An empty string is treated as absent - a script reads
undefined rather than "" - and a non-string is a 400
('requestName' must be a string). See
scripting.md.
allowScriptRequests lets this payload's scripts use pm.sendRequest.
Absent, null or non-boolean all mean false, and that default is a security
control rather than a convenience (issue #302): Vayu's MCP target allowlist is
checked in the MCP server, before it calls this endpoint, and held by the
engine to the URL a send is about to dial (targetPolicy), so
a request issued from inside a script with pm.sendRequest never passes
either. Denying unless a caller asks means
a client that forgets gets a script that cannot send rather than unchecked
egress. The app's Send and load runs send true; the MCP server never does.
POST /runs reads the same field for a script.post element's deferred
validation (its requestElements, below), so one script behaves the same on
both. Read before the stream branch, so a
streaming send's scripts are governed by it exactly as a buffered send's are -
the app sends it on both halves of Send (issue #653). See
scripting.md.
elements is the only script source, and it runs (issue #1514's cut-over,
replacing #1513's preRequestScript(s) / postRequestScript(s)). A caller
still sending any of preRequestScript, preRequestScripts,
postRequestScript, postRequestScripts or tests - even naming one with
null is accepted as a no-op, but a real value is not - is refused with a
400 naming elements as the replacement, before any run row exists. For
the by-id path, an element list a caller supplies inline is laid over POST
/compose's own resolved chain (collection root to leaf, then the request's
own, minus anything disabled or named by an inherit.disable entry, each
stamped with origin: {kind: "collection" | "request", scope, id, name?})
exactly as any other inline field overlays the stored one; an inline-only send
has no chain to resolve one from, so its elements carry no origin. scope
is collection for the root, folder for every collection below it and
request for the request's own (#2522); kind keeps its two values. It is
what each script result's scope (below) is read from, falling back to
kind for an origin that carries none.
elements is validated like a stored request's (#3052): a list the element
registry refuses (an unrecognized kind, a setting the kind does not declare, a
pattern that does not compile, an assertion with nothing to compare against, a
repeated id, a script.setup on the request, a value that is not an array) is a
400 carrying the message POST /requests answers for the
same list, before any run row exists and with nothing sent. An entry without an
id is given one rather than refused. The list is a composed one, so an entry
whose origin.kind is collection (a collection or folder level) is judged as
a collection's own, each on its own: it may be a script.setup or
script.teardown, and ids repeated across levels are allowed. Every other entry
is judged together as a request's, and an Item N in a refusal counts within
those. null or an absent elements sends none.
vayu::core::ElementPipeline runs the compiled list at each phase this send
reaches: script.pre elements at step.before, immediately before the
transfer (so a pm.request edit reaches the wire); extract.* / assert.* /
script.post elements at step.after, once the response (or, for a
streaming send, the terminated stream) is in. Every level's script runs, in
list order, and each one's tests and console lines are added to the step's
result rather than replacing an earlier level's (#2522). assert.* outcomes append to
the same pm.test() channel a script.post element's assertions do, so the
response body's testResults and consoleLogs (see below) do not
distinguish a declarative assertion from one a script wrote by hand. The
response body and the stored trace both carry an elements array beside
scripts - one entry per element that ran, each {id, kind, name?, origin, required?,
outcome, message?, waitedMs?} (name the element's own label, when it has one;
required present, as true, only for an element whose config.required is,
which makes an extractor's missing a failed send) with outcome one of ok | failed |
missing | skipped | error (a disabled element reports skipped without
its apply ever running; a script element reports error with the thrown
message when its script threw and failed with the first failed pm.test as
its message when only assertions did not hold; an assert.* that reports
error because its own config cannot be judged, a row stored before #3043,
also adds a failed entry to testResults under the same message, so the send
fails) - see Elements.
The pre-request script can change what is sent. Its pm.request edits -
method, url, headers, body - are applied to the request before it goes out, and
because auth is resolved before the script runs, a script-set Authorization
overrides the one the engine applied. A credential that waits on the script
(#2473) is applied after it instead, and a script-set Authorization still
wins: auth never replaces a header the request already carries.
requestHeaders and rawRequest in the response below, and the stored trace behind GET /runs/:id, all report the
post-script request. A value the engine cannot send (a non-string url, an
unknown method) rejects the whole write-back, leaves the request unchanged, and
is reported as preScriptError. See
scripting.md.
Redirect policy. followRedirects defaults to true, so omitting it
follows every 3xx and the final response is returned as the answer, with the
earlier hops' status and header lines on its redirects member (field notes
below the response example) - send followRedirects: false to make the 3xx
itself the answer. A chain longer than maxRedirects (default 10) fails the
send with TOO_MANY_REDIRECTS rather than returning the last 3xx. Both
clients send these explicitly for exactly that reason (see
api-integration). POST /runs accepts the same
three fields with the same defaults, so a load test can be run under the policy
the request was configured with.
TLS verification. verifySSL defaults to true and is stored on the
request (requests.verify_ssl, the Settings tab's Verify TLS certificate
row). Both clients send it on every execute and every load test rather than
eliding the default, for a stronger reason than the redirect policy above: an
omitted false verifies the certificate the user turned verification off
for, so the request fails against the one host the setting exists for. Off
skips both the chain and the hostname check (CURLOPT_SSL_VERIFYPEER and
CURLOPT_SSL_VERIFYHOST), which is why the app paints the state as a warning.
To keep verification on for a host with an internal authority, add the CA under
TLS trust settings instead.
A redirect hop's cookie stays with the origin that set it. On a design
send, a stream and a scenario load run's per-virtual-user session, a
Set-Cookie returned by one hop is stored in the cookie jar under
the origin that set it, exactly as before, but is applied to the follow-up
request only when that request's origin - scheme, host and port - is the
same. A redirect that changes any of the three therefore starts without the
hop's cookie: that includes a port-only change (127.0.0.1:8080 to
127.0.0.1:9090) and a hop to a sibling domain. A same-origin hop is
unchanged, and a hop back to the origin that set the cookie carries it again.
Later requests use the jar as normal. This is Vayu's own rule, held by the
engine's redirect loop, and it is not configurable. The reason is the one
behind curl 8.21.0's hardening (http: don't pass on set cookies to new
origins, which the engine picked up with the vcpkg baseline bump of #679):
what one origin handed the client is not the next origin's to read. libcurl's
cookie engine matches by host and path alone, so without the rule a cookie set
on 127.0.0.1:8080 would ride a redirect to 127.0.0.1:9090. A flow that
depended on a cookie surviving a cross-origin hop (a login that bounces
through an identity provider is the usual shape) sends the follow-up request
without it. A hop's Set-Cookie is reported in redirects whether or not a
later hop carried it, so the member says what the server sent, not what went
on to the next origin.
Protocol. httpVersion selects which HTTP version curl attempts:
"auto" lets ALPN negotiate (curl's own default), "http1.1" forces
HTTP/1.1, and "http2" attempts h2 over TLS and falls back to 1.1
(CURL_HTTP_VERSION_2TLS - against a plain http:// URL this silently
negotiates 1.1, since h2 is not offered over cleartext). A server on http://
that speaks only h2c answers that HTTP/1.1 request with its HTTP/2 preface,
and the send fails as PROTOCOL_MISMATCH with a hint naming h2c (the
transport error codes are described under Proxy settings);
serve it over TLS or let it accept HTTP/1.1, since Vayu never sends h2c. This
is what was requested; the response's own httpVersion (below) reports what was
actually negotiated, and the two can differ. The renderer always sends this
field on every execute, never eliding it even when it equals the default - the
same rule followRedirects follows, and for the same reason: an omitted field
lets an engine-side default win silently. MCP's saved-request paths get the
same guarantee from POST /compose, which always emits a stored request's
execution options; its two ad-hoc tools (run_request / start_load_run)
forward httpVersion only when the caller supplies it, since there is no
saved request behind an ad-hoc call for an omission to silently override (see
mcp.md). It governs both Send and load test -
POST /requests/PUT /requests/:id is where a request's protocol is actually
stored (see Requests above); POST /runs (below) is simply the
run-shaped way of stating the same field, not a second store.
Response:
{
"status": 200,
"statusText": "OK",
"headers": {
"content-type": "application/json"
},
"headerLines": [
{ "name": "Content-Type", "value": "application/json" }
],
"redirects": [
{
"status": 302,
"statusText": "Found",
"headerLines": [
{ "name": "Set-Cookie", "value": "session=abc; Path=/" },
{ "name": "Location", "value": "/users" }
],
"url": "https://api.example.com/login",
"schemeDowngrade": false
}
],
"requestHeaders": { "accept": "*/*" },
"requestHeaderLines": [
{ "name": "accept", "value": "*/*" }
],
"rawRequest": "GET /users?access_token=... HTTP/1.1\n...",
"authQueryParam": "access_token",
"body": { "id": 1, "name": "John" },
"bodyRaw": "{\"id\":1,\"name\":\"John\"}",
"bodyEncoding": "utf8",
"bodySize": 20,
"bodyCapped": false,
"httpVersion": "HTTP/1.1",
"httpVersionDowngraded": true,
"warnings": [],
"timing": {
"totalMs": 245.5,
"wireMs": 245.1,
"queueWaitMs": 0.4,
"dnsMs": 5.2,
"connectMs": 12.3,
"tlsMs": 45.1,
"firstByteMs": 180.2,
"downloadMs": 2.7,
"engineMs": 3.4
},
"testResults": [
{
"name": "Token was issued",
"passed": true,
"source": "pre",
"scope": "collection"
},
{
"name": "Status is 200",
"passed": true,
"source": "test",
"scope": "request"
}
],
"consoleLogs": [
{ "source": "pre", "scope": "collection", "level": "log", "message": "token refreshed" },
{ "source": "test", "scope": "request", "level": "error", "message": "unexpected shape" }
],
"validation": {
"checked": true,
"valid": false,
"matchedStatus": "200",
"matchedContentType": "application/json",
"failures": [
{ "path": "/id", "message": "Value type not permitted by 'type' constraint." }
],
"failuresTotal": 1,
"unevaluatedKeywords": [{ "keyword": "unevaluatedProperties", "count": 2 }]
}
}
bodyEncoding says how to read bodyRaw (issue #2458), and it is always
present. "utf8": the whole body is valid UTF-8 with no NUL byte, bodyRaw is
that text and body its JSON parse (or null). "base64": anything else - an
image, a PDF, application/octet-stream, Latin-1 or Windows-1252 or UTF-16
text, a compressed body libcurl did not decode, text containing a NUL - and
bodyRaw is the bytes in standard padded base64, body is null, and
bodySize is still the number of bytes, not the length of the base64. The
check reads the whole body, not a sniffed prefix, and the engine decodes no
declared charset: a body that is valid UTF-8 is "utf8" whatever its
Content-Type says, and one whose charset=utf-8 is wrong is "base64", left
for the client to decode by the declared charset. A header value that is not
UTF-8 has no such field and is answered with U+FFFD in place of each bad byte.
bodyRaw of a "utf8" answer is the byte-exact text received; body is the
parsed convenience copy, whose member order is unspecified and in which a
duplicate key collapses to the last value. A client that shows or re-saves the
body should use bodyRaw, as the app does (issue #2459).
body is also null on a "utf8" answer that is valid JSON in two cases
(issue #2544): the request sent includeParsedBody: false (below), or the text
is longer than 4 MiB (MAX_PARSED_RESPONSE_BODY_BYTES), whatever the request
sent. Past that size the engine does not build the parsed copy at all, because
a JSON tree costs several times its text and the answer is serialised from it
once more; bodyRaw still carries the whole body, up to
maxDesignResponseBodyBytes below. The key is always present. Scripts, the
schema check and the stored trace read the body itself, so none of them is
affected.
So a response the server answered is a 200 whatever its bytes are; the end
of this section has the 500 that remains.
bodyCapped says the body is a prefix (issue #1157). A design-mode send
reads at most maxDesignResponseBodyBytes (Settings → Limits, default 32MB);
a response past that stops being read there, and body / bodyRaw /
bodySize describe what arrived rather than what was sent. The status and the
headers are the server's own - they arrive before the body - so this is a
successful response carrying a flag, not a transport failure. The field is
always present, so a client can tell "not capped" from an engine too old to
say, and re-sending under the same setting reads the same amount: raise the
setting to read more. Two consequences worth stating, since both follow from
reading less: a cut JSON body no longer parses, so body is null and a test
script's pm.response.json() throws, and validation below reports
checked: false with body_not_json rather than inventing a schema failure.
A body nested past 100 levels counts as not JSON for the same check, so a deep
body is never walked by the schema validator (issue #2413).
The cap falls on a byte count, so it can land inside a UTF-8 character. For a
capped body only, bodyEncoding is decided with that incomplete last character
(at most three bytes, and only bytes some continuation could still make valid)
left out, and a "utf8" bodyRaw ends before it: a text body stays text rather
than turning to base64 over its last character. bodySize still counts every
byte read, so it can exceed the UTF-8 length of bodyRaw by up to three. A
"base64" body is never trimmed, and a body that was not capped is judged
whole. The stored trace makes the same decision on the same bytes.
This is not the stored trace's bodyTruncated (see GET /runs/:id), which
is maxTraceBodyBytes shortening a body for storage after the whole of it was
read and shown - a re-send recovers from that one. A design run whose live
response was capped stores trace_data.response.bodyCapped, so a restored
response says what the live one said.
A body the live answer sent as bodyEncoding: "base64" is stored the same way:
trace_data.response.body holds the base64 and trace_data.response gains
"bodyEncoding": "base64". The key is written only then; absent means the
stored body is the text itself, which is what every row written before the
field holds. A collection run's step traces follow the same rule.
validation is what the response was against the schema its contract
declares (issue #628), and it is absent entirely for a request whose
collection ancestry binds no OpenAPI document. That absence is load-bearing: a
response nobody judged against a contract did not fail one, so there is no
checked: false for it either.
The same object is stored on the design run's trace_data.validation, so a
restored response shows the verdict the live one did rather than recomputing it.
A streaming send carries none - an event stream is not a document a response
schema describes.
testResults lists both scripts' assertions in execution order, each
naming the script that made it in source ("pre" / "test", the spellings
consoleLogs uses) - pm.test is bound in both phases, and until issue #810 a
pre-request assertion failed a collection-run step while appearing in no list.
An entry stored before that carries no source; it is a test script's, which is
all the list held.
A request runs the scripts of every level it inherits from - the collection's,
each folder's from the outermost in, then its own - and every level's results
are listed (#2522). Each testResults and consoleLogs entry names its level
in scope: collection, folder or request. It is not level, which a
console line already uses for the console method. An entry stored before the
field carries no scope and is the request's own; so is one from a payload
whose elements carry no origin. success folds the same way: a failing
pm.test at any level is a failed assertion, and the first level that throws
is the error. preScriptError / postScriptError hold the thrown message as
they always have when the request's own script threw (never empty or a bare
null: a script that runs out of memory reads Script ran out of memory at the
1 MiB limit, see
Error Handling); when an inherited level
threw, they name it - "Collection pre-request script failed - assert.* or extract.*
element's entry carries the scope of the level that declared it.
The four script keys are stored the same way (issue #725). testResults,
consoleLogs, preScriptError and postScriptError are returned in the body
above and written to the design run's trace_data.scripts as one object, so a
response restored from History carries the assertions the live one showed. This
used to hold for a streaming send only, which made a restored ordinary send's
Tests pane empty whether its assertions passed or never ran. A send whose
scripts said nothing stores no scripts node at all - absent means no scripts,
not no results - and a transient execution stores neither, as it stores
nothing.
| Field | Meaning |
|---|---|
checked |
Whether anything was actually validated |
valid |
Present only when checked. A body with no failures |
reason |
Present only when not checked - the code, see below |
failures[] |
path (a JSON Pointer into the body; an unexpected property is at its own pointer, /o/z with unexpected property 'z') and message, capped at 10 |
failuresTotal |
Every failure found, including any past the cap |
unevaluatedKeywords[] |
Schema keywords the validator could not evaluate, by name and count |
matchedStatus / matchedContentType |
Which declared response answered, verbatim |
A status answers to the most specific pattern that covers it - exact, then
2XX, then default - the same rule contract coverage counts by, shared rather
than restated, over the same set of statuses: every one the operation declares,
whether or not it carries a schema (#3028). A declared 200 with only a
description therefore answers a 200 itself and is no_schema_for_status; a
default or 4XX beside it never judges that body. A media type matches
exactly first, then a declared */* or application/*, among the media types
that carry a schema.
unevaluatedKeywords is the dialect disclosure and is not decoration. The
validator reads draft-07; OpenAPI 3.1 schemas are JSON Schema 2020-12, whose
unevaluatedProperties, prefixItems and dependentSchemas a draft-07 reader
silently ignores - so a schema that meant to forbid something would permit it.
Every such keyword is named and counted, which makes a valid: true beside one
narrower than it looks rather than wrong.
propertyNames is the one draft-07 keyword on that list, and only when it is
nested (#2729): valijson builds a propertyNames subschema from its parent's
node path, so it validates the schema's root keyword but passes every body for
one inside properties, patternProperties, additionalProperties, a
dependencies schema, an allOf/anyOf/oneOf/not member, items or a
$ref target. Each nested
occurrence is counted once, a $ref target reached twice included; the root
keyword is validated and counted only when a $ref back to # reaches it from
below. In a script, pm.response.to.have.jsonSchema fails in both polarities
on such a schema, as it does for any unevaluated keyword.
reason codes (all mean bound to a document, and still not judged):
| Code | What happened |
|---|---|
no_operation |
The request carries no spec_operation - it is not an operation |
no_index |
The bound document declares no response, or its schema could not be read (including one that refers to itself without describing any value, which is refused before it can run) |
hash_mismatch |
The stored document no longer hashes to what the binding recorded |
never_stamped |
The binding names a document and no version of it, so nothing can be compared - re-bind the collection. Distinct from hash_mismatch because a sync of an unchanged document would not repair it |
operation_not_declared |
The document does not declare this identity (the operation is not in the spec, or declares no response at all) |
no_schema_for_status |
Nothing the operation declares covers this status, or the status that answers it declares no schema to check a body against |
no_schema_for_content_type |
The status matched; none of its media types did |
no_response |
A transport error - there was no response to check |
body_not_json |
The body is not JSON (or nests past 100 levels, which counts as not JSON), and a JSON Schema cannot describe it |
headers is keyed by the lower-cased header name, and a name the response
sent more than once holds every value folded with ", " - the RFC 7230 §3.2.2
equivalence for comma-list headers. So two Set-Cookie lines read back as one
"session=abc; Path=/, csrf=xyz; Path=/" entry rather than the last one alone.
headerLines is the lossless form of the same headers (issue #2460): one
{name, value} object per line the final response sent, in wire order, with the
name in the case it arrived in and the value trimmed of the optional whitespace
around it (RFC 9110 §5.5). A name sent twice is two entries, and a Set-Cookie
is always its own entry, so a client lists headers as received and reads each
cookie from its own line. It is always present on a design answer, an empty
array when no headers arrived, so a client can tell "none" from "an engine too
old to say" - the same rule as httpVersion. A streaming send (stream: true)
reports it on the completed trace, while its open frame carries the folded
headers map only. The map is unchanged and stays what assertions and the
MCP headers member read; pm.response.cookies and MCP's headerLines
read the lines. Splitting a folded Set-Cookie out of headers is now
needed only for a row stored before this field and an answer from an older
engine, and it must split on a comma followed by name=, since an Expires=
value contains a comma of its own (a cookie value that holds one is
indistinguishable from a boundary there, which is why headerLines exists).
The same headers fold holds for the response headers stored on a design run's
trace_data.response and on captured load-run samples, which come off the same
parse. The stored trace_data.response also carries headerLines, written only
when non-empty; a load-run sample keeps the folded map alone, because the load
path is the hot path and records no lines.
redirects lists the redirect responses the
send followed (issue #2461), in the order they arrived, each as
{status, statusText, headerLines, url, schemeDowngrade} with headerLines
shaped as above. headers
and headerLines hold the final hop only, so a Set-Cookie or Location on an
earlier hop - the 302 that answers a login and sets the session cookie - is
readable nowhere else. url is the URL of the request that hop answered: the URL the
send went to for the first hop, the previous hop's Location resolved against it
for each later one (userinfo is removed), with the value of the request's auth-written query parameter, and
of any query parameter named like a credential, blanked; "" when libcurl
reported none. schemeDowngrade is true when that
request went over https and the next one over http: the one hop on which an
API-key header, which a redirect does not withhold, travels in clear text (see the
Redirects paragraph under Authentication). A row stored before these two members
existed lacks them. Only 3xx responses are hops: a 1xx interim response
such as 100 Continue is not. It is always present on a design answer, an empty
array when nothing was followed (followRedirects: false always gives an empty
one, the 3xx being the answer), and holds at most maxRedirects entries (every
hop when maxRedirects is negative, which sets no limit), so a loop that ends
in TOO_MANY_REDIRECTS reports the hops it made. The stored
trace_data.response carries it too, written only when non-empty; a load-run
sample records none. It reports what the server sent: see the cross-origin
paragraph above for why a hop's cookie is not necessarily one a later hop carried. A post-request script reads
the same hops as
pm.response.redirects
(code/status/headers for status/statusText/headerLines), absent where
the chain is not recorded.
warnings lists what the engine did to the exchange that the response does
not show (issue #3307), each as {code, message} in the order it was found:
code is a stable snake_case identifier a client branches on, message the
sentence a person reads. A warning never fails the send. It is always present on
a design answer, an empty array when there is nothing to say, so a client can
tell "no warnings" from an engine too old to warn. The stored
trace_data carries it at the top level, beside clientCertificate and not
inside response, because a send that failed before any header block
arrived has no response node and can still have warned; it is written
only when non-empty, so a row
stored before the field reads as having none. A load-run sample records none.
Codes are listed here as the engine starts producing them:
cookie_not_sent: libcurl would not let theCookieline pass 8190 bytes and left out the first jar cookie that did not fit, named in the message (the name only, never a value). It also drops every typedCookierow with the line, sorequestHeaderscarries noCookieentry then. libcurl skips the jar cookies after the named one without saying so.-
cookie_limit_reached: more than 150 jar cookies matched the URL and libcurl sent the first 150. A typedCookierow is still sent in this case. -
cookie_dropped_oversized: a response carriedSet-Cookieheaders libcurl discarded unread, because the line was over 5000 bytes (counted from afterSet-Cookie:to the end of the line) or the cookie's name and value together were over 4096. One warning counts them, across every hop, and names up to five (name only, cut at 64 bytes; a line that names no cookie, or whose name is not text, is counted but not named). cookie_dropped_too_many: a single response set more than 50 cookies and libcurl ignored the rest. The count restarts with each hop's response, so 30 cookies on each of two hops is not an overflow; one warning gives the total ignored over the chain. It counts theSet-Cookielines libcurl would have stored, so a later cookie it rejects for another reason (a public suffix, a__Secure-prefix) can make the count one too high.
cookie_not_sent and cookie_limit_reached are read off libcurl's own notices
at any log verbosity, once per cookie however many hops of a redirect chain
report them. The two cookie_dropped_* codes are counted from the response's
header lines instead, only on a send that has a cookie jar. A streaming send
(stream: true) reports all four by the same rules, on its stored trace alone.
Under load the same two checks feed the run's cookies_dropped warning instead
(see GET /runs/:runId/report).
rawRequest is the header block libcurl actually sent, captured from the
transfer's last outbound header frame and followed by the request body when
that frame declares one (Content-Length above zero, or Transfer-Encoding:
chunked). So it carries what libcurl added on its own - the cookies the
cookie jar matched, Accept, Content-Length,
and an h2 request rendered in HTTP/1 form - none of which appear in
requestHeaders. The jar's cookies and the request's typed Cookie rows share
one Cookie line, the jar's first and the typed rows after them joined with
"; " (issue #2788); a redirect to another scheme, host or port drops the
typed part, as it drops a typed Authorization. The app's Headers tab lists the sent request
from this block, line by line in wire order, so the tab shows the whole wire while the
script-visible record stays the engine's. When the final hop sent no body, the
string ends at the blank line that closes the header block: a POST answered
301, 302 or 303 is re-sent as a body-less GET (any other method keeps
its name and loses its body, a streamed file body included), without the Content-Type and Content-Length
lines that described the body, so the body it started with is not shown on a
request that never carried it (issue #2462). 307 and 308 keep the method
and the body, and so does the view.
requestHeaders is the sent record: the composed headers as the transfer
issued them on its first hop. After a followed redirect that changes the
request (a POST answered 303, which becomes a GET) the final hop's own
header block is rawRequest's. It carries what the engine derives at send
time - the body-implied Content-Type (text/plain for a text body since
issue #2464), and every default header this send
adds (the User-Agent, the negotiated Accept-Encoding, an enabled
correlation id) - and drops a form-data Content-Type, which libcurl writes
itself with the boundary. An enabled header whose value is empty or only
whitespace is sent empty on every transport (issue #3220) and recorded with
the value "": a header line with nothing after the colon is libcurl's spelling
for remove this header, so the engine writes libcurl's Key; form instead,
which sends Key: with no value. A blank row never removes a header; refusing
one of the engine's defaults is disabledDefaultHeaders' job. A blank Accept
or Expect row is therefore sent empty in place of libcurl's own Accept: */*
or Expect: 100-continue. Two blank rows keep a meaning of their own and are
neither sent nor recorded: a blank Content-Type means no Content-Type (on a
binary body, absent, so the file's type applies; see
the body union), and a blank Cookie row joins
nothing into the cookie line. A disabled row is never sent. The record
does not carry libcurl's own additions or the jar's Cookie line; those are
rawRequest's alone. A test script's pm.request.headers reads this same set
(see scripting.md), so an assertion
about what was composed to go out reads the same set the engine recorded; the
Headers tab lists rawRequest's header block instead, which is that set plus
the transport's own lines.
requestHeaderLines is the same record unfolded (issue #2466): one
{name, value} entry per line the transfer appended, in wire order, a repeated
name repeated and each in its own spelling - the request's own lines first, in
the order the request gave them, then what the engine derived. Always present,
an empty array when nothing was recorded. requestHeaders stays one value per
name for the readers written against it: a repeated name's values are joined
with ", ", a Cookie's with "; ", under the first line's spelling - and
that folded form is what pm.request.headers shows, since the scripting API is
single-valued.
The stored trace keeps this map too, as trace_data.request.sentHeaders
beside the composed request.headers (issue #664), and the unfolded lines as
trace_data.request.sentHeaderLines (issue #2466) - so a restored response
pane's sent-headers disclosure shows the set the live one showed, derived
User-Agent and body-implied Content-Type included, rather than the composed
map's different answer. Both maps are stored because they answer different
questions: the composed one is what a pre-request script saw and what reseeds
a request tab from a run. The key is absent on a step that sent nothing and
on every row written before the field, so a reader falls back to
request.headers - restore-response.ts's sentSide is that reader. A load
run's sampled capture records no sent headers at all: its deferred replay and
the Samples viewer both keep reading the composed map, as
scripting.md documents. That map can
differ from the wire in the way this record exists to state - the derived
User-Agent and body-implied Content-Type are absent, and a blank
Content-Type or Cookie row, which is not sent, is listed - and for load samples
that divergence is recorded as permanent rather than treated as a gap to
close (issue #677 item 7). Which completions become samples is decided when they
finish, so a sent record for the few that are kept would have to be built for
every transfer, and a load run exists not to charge the hot path for what it
throws away.
Values in rawRequest are not redacted:
this field exists to say exactly what went out. On a followed redirect it is the
final hop - its method, its headers and the body that hop carried, if any -
matching the response beside it. A transfer that failed before
sending anything (DNS failure, connection refused) has no frame to read, and
falls back to a request synthesized from what was composed.
The stored trace keeps the same string, as trace_data.request.rawRequest
on the design run this execute created (and on each step row of a scenario run)
- so reopening a run shows the raw request the live view showed, cookies
included, rather than one rebuilt from headers that never had them. Its body
half is capped at maxTraceBodyBytes like body is, and the key is absent both
on a step that sent nothing and on rows written before the field existed; see
db-schema. The redaction posture is the live field's,
for the reason Security records: a trace is the
record of what was sent.
The answer and the stored trace also name what auth wrote (#1835, #1845),
as two additive keys: authQueryParam, the raw (unencoded) name of the query
parameter apply_auth appended to the URL for an API key with in: "query" or
an OAuth 2.0 token with tokenPlacement: "query", and authHeaders, the array
of header names an API-key block filled. The URL alone cannot say which query
parameter is a credential, and a reader that masks one (the MCP server) needs
the name. In the trace they sit on trace_data.request; in this answer they sit
at the top level, beside rawRequest, written by the same function
(record_auth_provenance) so the two cannot disagree. Each key is absent
when auth wrote none of that kind, never an empty string or array - unlike the
response fields above, which are always present - and absent on rows written
before the field; the values beside them stay raw. A streaming send answers
202 before any of this exists, so only its stored trace carries them. A
pre-request script that retargets the URL can leave authQueryParam naming a
parameter the final URL no longer carries.
And they say when auth was not sent at all (#2474): authNotice, a plain
string, appears when the request's auth.mode is one the engine stores but does
not execute (digest, aws, ntlm, hawk, oauth1, edgegrid, jwt; an
import can bring any of them in). The request is still sent, without
authentication, and the notice says so, naming the mode:
"authNotice": "auth mode 'ntlm' is not executed by Vayu; the request was sent without authentication"
It appears too when an executed mode had nothing to write (#3203): a bearer
token, or an apikey key, that is empty once trimmed of its spaces and tabs.
The request is sent without that credential rather than refused:
and, for the API key, "the API key has no name; the request was sent without
it".
It also appears when an oauth2 block placing its token in the header yielded to
the Authorization header the request carried, so no token was fetched (#3202):
the request's own Authorization header was sent; no OAuth 2.0 token was fetched.
It follows the same rules as the two keys above: one writer for both homes,
absent when empty (no auth, and an executed mode that wrote its
credential, or skipped it under a header the request already carries), absent
on rows written before the field, and on a streaming send only in the stored
trace. A pre-request script that assigns pm.request.auth replaces the notice
along with the credential: the record then describes the script's auth, so it
is absent unless the script's own token or key name is empty.
A collection run's stored step traces carry it through the same trace writer;
a load run sends such a request the same way and raises no run warning for it.
consoleLogs entries carry their own source and level. source is which of
the request's two scripts wrote the line ("pre" for the pre-request script,
"test" for the post-request one) and level is the console.* method that was
called - "log", "info", "warn" or "error". Releases before this one sent
a flat string[] with the source encoded as a "[pre] " text prefix and no
level at all, which was indistinguishable from a script logging that string
itself; a client that may talk to an older engine should read a bare string as
{"source": "test", "level": "log"}, or "pre" when the prefix is present. The
field is omitted entirely when neither script logged anything. Each script
execution keeps at most 1000 lines and 1 MiB (64 KiB a line); a script that
passes either ends its entries with one warn line saying output was dropped.
See scripting.md.
httpVersion on the response is the protocol actually negotiated
(CURLINFO_HTTP_VERSION after the transfer), e.g. "HTTP/1.1" or "HTTP/2" -
an outcome, not an echo of the request's own httpVersion field, and
deliberately a different value space (see
requests.http_version for the full distinction). It is
"", not omitted, when nothing was negotiated (e.g. the connection never
reached a server) - empty rather than guessing "HTTP/1.1" and presenting a
guess as fact. The same field is stored in a design run's trace_data.response
and reported back unchanged by GET /runs/:runId and
GET /runs/:runId/report.
httpVersionDowngraded is true when the request explicitly asked for
"http2" and the connection negotiated something older - the one thing the two
httpVersion fields cannot say on their own, since neither knows about the
other. It is always present (never omitted), so a client can tell "not
downgraded" from "an engine too old to say". Only an explicit http2 counts:
"auto" promises nothing and "http1.1" got what it asked for, so neither can
be downgraded. A transfer that negotiated nothing at all (httpVersion "")
is false - that is a transport failure, and errorCode already reports it.
A plaintext http:// URL always reports true for an explicit "http2".
CURL_HTTP_VERSION_2TLS offers h2 over TLS only, so a cleartext request never
attempts it - the fallback noted above under the request's httpVersion is
exactly the case this field is for, and it is honest rather than a false
positive: h2 was asked for and HTTP/1.1 was used. A local dev server on
http:// with the protocol set to HTTP/2 will show the warning on every
request; either switch the request to auto, or serve over TLS. A server
there that speaks only h2c never gets as far as a downgrade: it cannot read
the HTTP/1.1 request, so the send fails as PROTOCOL_MISMATCH with the h2c
hint instead, and auto meets the same failure without the hint.
This exists because the failure it names is invisible otherwise: a 200, a
latency and a body look identical whether or not the protocol you asked for was
granted. Windows shipped from v0.11.0 to v0.14.0 with HTTP/2 unreachable and
every request silently on HTTP/1.1 (#215);
nothing in the API said so. The same field is stored on a design run's
trace_data.response, and load runs and collection runs carry the
whole-run count as summary.httpVersionDowngraded in
GET /runs/:runId/report.
One timing convention. The eight phase keys above (totalMs through
downloadMs) are the same *Ms names the stored trace uses
(record_design_result / load_strategy → results[].trace in
GET /runs/:runId/report), and the design-mode writer stores all eight
unconditionally - so a live response and one restored from the stored trace
carry the same fields with the same names, Wire/Queue included. Traces written
by earlier releases differ two ways, and readers must tolerate both: stored
rows omitted zero-valued phases and all of totalMs/wireMs/queueWaitMs
(see db-schema.md), and the live response named its keys
without the suffix (firstByte, dns, …) - consumers of the raw /execute
body written against that dialect must switch to the *Ms names.
refusalCode and authErrorCode say why a send never went out. Both are
absent from an answer that was sent. A buffered send refused after the
build and before the transfer (the residual pass of a name or header, the
auth applied after the pre-request script, a targetPolicy
verdict) answers statusCode: 0 with the sentence in errorMessage and the
rule's code in refusalCode: unsendable_header, empty_header_name,
invalid_header_name, colliding_header_names, target_not_allowed,
target_host_unknown, or an auth code. authErrorCode is the hint of an auth
failure (errorCode AUTH_REQUIRED or AUTH_FAILED), whether the token was
sought at the build or, for a config that waited for the script, after it
(where it repeats refusalCode, #2521). A streaming send answers the same
codes as a 400 before its stream opens.
wireMs and queueWaitMs split totalMs at the wire (#2394).
totalMs is perceived: submission to completion. wireMs is libcurl's
CURLINFO_TOTAL_TIME less the time libcurl held the transfer waiting for a
connection slot (CURLINFO_QUEUE_TIME_T, bounded by PRETRANSFER_TIME
because curl 8.23 counts a wait again each time the transfer is passed over),
and queueWaitMs = totalMs - wireMs is everything before the wire: the
generator's own queue and that slot wait. The phases are measured after the
slot wait too, so firstByteMs is the target's own. A design send has no
slot to wait for, so its queueWaitMs stays a sliver. Over a followed redirect
chain the phase fields accumulate: every hop's libcurl timers are summed
(add_phase_times), so firstByteMs is then the sum of each hop's wait, not
one server's, and dnsMs, connectMs, tlsMs and downloadMs are sums the
same way. The app's Timing tab says so when the response's redirects is
non-empty.
timing.engineMs is Vayu's own cost for the exchange (#2132),
the ninth key and the only one a buffered /execute alone carries. It is the
time from the handler receiving the request to the answer being assembled,
less the transfer (wireMs), the pre- and post-request scripts
(pm.sendRequest inside them included) and the time spent waiting on an
OAuth 2.0 identity provider's token endpoint (a token fetched on first use, or
refreshed because it expired; a cached token costs a lookup and stays in). What
it counts is request composition, the rest of auth resolution, the cookie jar,
residual {{token}} resolution, the element pipeline other than the user's
scripts (extractors, assertions, metrics) and building the response;
queueWaitMs, the sliver between the engine's stopwatch and libcurl, is part
of it. A design send blocks on no timer, so there is no timer wait to leave
out. It does not count the wire, scripts, the token endpoint, the hop from the Electron shell to the engine, persisting the run row
and trace, serialising the body, or the renderer drawing it: the figure is
taken once, before the write, and that same value is both returned and stored
on the trace as a flat engineMs, so a restored response shows what the live
one did. It is absent - not 0 - from a streaming send (the route answers
202 before any exchange finishes), from the auth-failure reply (no exchange
ran), and from rows stored before this key existed.
Variables the scripts and extractors wrote are persisted, and only those.
After the post-request elements run, the engine writes back the three variable
scopes (the run's environment, globals, and the executed request's collection) -
but only for a scope whose variables a script or an extract.* element actually
changed, a name removed included (an unset, or an extractor's miss with no
default, #3053). A run that sets no variable writes nothing at all, so it does not move
a collection's or environment's updatedAt. Each variable round-trips whole,
createdAt included; see VariableValue shape
for why that field must survive and who may stamp it.
persistVariables: false keeps them within the send (#1904). Every script
and extractor still runs, a value one sets is visible to the elements after it,
and the response (or a stream's trace) reports their outcomes and testResults
as usual; only the write-back above is skipped, on both the buffered and the
streaming path, so no environment, collection or globals row changes. Absent
and null mean true, which is what the app's Send relies on; a present
non-boolean is a 400 ('persistVariables' must be a boolean) before any run
row exists, for the reason transient's is. It is independent of transient:
that flag decides whether the run is recorded, this one whether the
variables are. MCP's run_request sends false whenever write access is off
(MCP).
includeParsedBody: false leaves the parsed copy out (#2544). The answer's
body is null and the engine skips the parse that would build it; bodyRaw,
bodyEncoding, bodySize, the scripts' pm.response, the validation node
and the stored trace are what they would have been. It is for a client that
reads bodyRaw only and should not pay for a second copy of every body. Absent
and null mean true; a present non-boolean is a 400
('includeParsedBody' must be a boolean) before any run row exists, by the
rule transient's follows. A body past 4 MiB is never parsed whatever this
says (see the response section above). A streaming send has no body in its
202 and ignores the flag.
A run row the database cannot write is a 500. A recorded send whose run row
cannot be stored (a busy or locked database, a full disk, an I/O error) answers
500 Couldn't create the run record before anything is sent, the same as
POST /runs. The app retries a 5xx and treats a 4xx as a
verdict, so a momentary lock no longer reads as a refused request (#2353). A
transient send writes no row and is unaffected.
A send that fails once its row exists is a 500 with a body, and a failed
row (#2458). Anything that throws after the run row is written - building
the answer, running the exchange, handing a stream to its worker - answers
500 Execution failed: <reason> in the usual {"error": {"code",
"message"}} shape and marks the row failed, even when its result had
already been recorded, so GET /runs/:runId never shows a send the caller got
no answer for as running or completed. A body the engine cannot hold as
text is not such a failure: it is a 200 with bodyEncoding: "base64", above.
POST /runs¶
Start a load test run (Vayu Mode).
Request:
{
"method": "GET",
"url": "https://api.example.com/users",
"headers": [], // Optional, {name, value} lines in send order (or the older object) - see POST /execute
"body": {
"mode": "none",
"content": ""
},
"mode": "constant_rps", // "constant_rps", "constant_concurrency", "ramp_up", "iterations", or "capacity"
"concurrency": 100, // Target in-flight requests (constant_concurrency / ramp_up target / iterations); the ceiling for capacity
"startConcurrency": 1, // Ramp start concurrency (ramp_up); first level searched (capacity)
"duration": "60s", // Duration, ms/s/m/h (constant_rps / constant_concurrency / ramp_up); the deadline for capacity
"rampUpDuration": "10s", // Ramp time, ms/s/m/h (ramp_up mode; start may be above target)
"sloMs": 200, // p99 budget the search looks for the edge of (capacity mode)
"stepDuration": "5s", // How long each level is held before it is judged (capacity mode)
"iterations": 1000, // Number of iterations (iterations mode)
"targetRps": 1000, // Target requests per second (constant_rps only; a 400 on any other mode)
"maxInFlight": 10000, // Optional; see "maxInFlight" note below - constant_rps only
"requestId": "req_1234567890", // Optional, links to saved request
"requestName": "Create user", // Optional, read by the deferred validation script as pm.info.requestName
"environmentId": "env_1234567890", // Optional, what {{variables}} resolve against - see below
"collectionId": "col_1234567890", // Optional, the composed collection scope when no requestId row names one - see below
"origin": { "kind": "mcp", "client": "claude-code" }, // Optional, who started the run - see below
"targetPolicy": { "allowAll": false, "allowedHosts": ["api.example.com"] }, // Optional, the hosts this run may reach - see below
"requestElements": [], // Optional step-level elements for THIS request - see below
"data": [], // Optional data rows, one object per row - see below
"dataFileName": "users.csv", // Optional, only beside data: the file's display name - see below
"dataFileHash": "<sha256>", // Optional, only beside data: 64 lowercase hex chars - see below
"dataFileCastNumbers": true, // Optional, only beside data: the file's numbers were read as numbers - see below
"thresholds": {}, // Optional pass/fail budgets - see below
"carriedBudgets": [], // Optional, which of those budgets were carried over rather than set - see below
"elements": {}, // Optional element-pipeline override, either run shape - see below
"lifecycleElements": [], // Optional script.setup/script.teardown for THIS run only - see below
"monitor": {}, // Optional server-vitals scrape - see below
"followRedirects": true, // Optional, default true - see POST /execute
"maxRedirects": 10, // Optional, default 10
"httpVersion": "auto", // Optional: "auto" | "http1.1" | "http2", default "auto" - see POST /execute
"stream": false, // Optional, single-request only - consume each response as text/event-stream; see below
"maxStreamDurationMs": 600000, // Optional, streaming only (a collection run's streaming steps) - see below
"maxStreamEvents": 100000, // Optional, streaming only (a collection run's streaming steps) - see below
"stream_metrics": true // Optional - feed the histograms behind the report's `stream` section
}
A body nested deeper than 128 levels in any field answers 400 request body
is nested deeper than 128 levels (code invalid_run_config) before any run row
exists (issue #2417). The exception is a data or scenario.data cell, held to
its own bound of 100 and refused in its own words (see below).
httpVersion on POST /runs is not a per-run override of a stored
request - it is simply how this endpoint states which protocol the run uses at
all, the same way method and url state the rest of the request. The
renderer always sends the saved request's own httpVersion here (there is no
second, load-test-only protocol control in the app); MCP's ad-hoc
start_load_run - which has no saved request behind it - is the caller that
actually depends on this field to specify a protocol in the first place. An
explicit null is treated exactly like an absent key. An unrecognized string
is a 400 naming the field and the valid values, the same validation
POST /requests uses.
requestId / environmentId / collectionId on POST /runs are read
exactly as on POST /execute: a non-string is a 400 naming
the field ('environmentId' must be a string (got boolean)) and no run row is
created. A single-request run's collection scope is decided by the same rule
(the linked request's collection, else the composed
collectionId, issue #3461), for its scripts,
its residual pass and its snapshot's masking alike. A single-request run that
names any of the three resolves a {{name}} still in its URL, path values,
headers or body against the same scopes a Send reads (the environment, that
collection's chain, globals) (#3253). It is one
pass at run start, over the request every submission shares, never one per
submission, so a request holding no {{ costs nothing more. An
id naming nothing is an empty scope, as on POST /execute, never a refusal.
The pass leaves every token the per-submission bind owns: {{data.*}} and a
bare column of the run's data, {{$vu}} / {{$iteration}}, and a
generator such as {{$guid}}, generated per submission. It runs before
script.setup, so a setup write does not reach a request it resolved. A run
whose submissions are copied skips it, leaving its request to the
per-submission residual pass described under
the requestElements array,
which reads what script.setup wrote: one whose requestElements hold a
step.before kind (a script.pre, the only one this path admits), or that
declares requestElements beside data rows, a token the bind owns, or a
credential waiting on the scripts. A run whose requestElements only read the
response (assert.status, step.after kinds) and has none of those sends one
shared request, and takes this pass (#3288). Which of the two a run is gets decided
on its request before this pass, so a stored value that is itself a generator
moves the run onto the copy path having already answered the name it filled,
and a setup write to that name is lost. Credentials holding a name these
scopes may answer are held back from the build on a run whose submissions do
not wait on their scripts for them, and resolved and applied by this pass after
the request's own names (#3288), so a bearer token, an api key in a header or
the query and a basic pair all go out with their values; one whose credential
also holds a token the bind owns ({{$iteration}}) has its stored names
answered here and is bound per submission. A credential holding no token is
applied when the request is built, as before. A name nothing answers is sent as
written and counted in the report's unresolved_tokens warning, never refused;
a credential the pass cannot apply (an api-key header name that resolves to
something that is not a header name, a value a header line cannot carry) is
counted the same way and the run goes on.
origin on POST /runs is the same object, read by the same reader and
under the same rules as on POST /execute (#1817): who started
the run, client-asserted metadata rather than identity, other when absent,
client kept for mcp only, and a malformed one a 400 naming the field
before the run row exists. It applies to every run shape this endpoint starts,
a scenario's included.
targetPolicy on POST /runs is the object POST /execute
documents (#2521), read by the same reader: a malformed one, an unknown member
included, is a 400 with code invalid_target_policy before the run row exists,
and it is never stored in the run's config_snapshot. What differs is where the
verdict is made:
- A single-request run has its OAuth 2.0
accessTokenUrlandrefreshTokenUrlhosts judged in the pre-flight, before any token is fetched and before the run row exists: a refusal is a400whose code istarget_not_allowedortarget_host_unknown. The request's own URL is judged at each submission, in the event loop after the transferability checks: a host the policy refuses fails that submission as anINVALID_URLerror whose message names the host, counted like any other error, and nothing is sent. - A collection run (
scenario) has the token endpoints of each step's OAuth 2.0 config judged when the plan is resolved wherever the token is acquired then, a400under the same codes with no run row. A sequential run then judges each step's final URL after that step's pre-request script, as a buffered send does (and a config that waited for the script, at its step), and a collection load run judges each submission as a single-request load run does. - A load run's
monitor.url(either shape) is a second host the run contacts, once per scrape for as long as it runs, and the scrape loop sends with no policy of its own, so its host is judged when the run is validated, by the same match (#3121), on the URL as the scrape will send it (after the encoding pass that turns a\into a/, as for a send's final URL): a host the policy does not list, or one it cannot determine (a{{template}}, which the scrape would send as written), is a400undertarget_not_allowedortarget_host_unknownwhose message namesmonitor.url, before the run row exists and before anything is sent. A caller that wants a monitor on another host lists that host too.
An omitted targetPolicy restricts nothing. Redirect hops and pm.sendRequest
are outside it.
Streaming under load (stream)¶
POST /runs reads stream, maxStreamDurationMs and maxStreamEvents
through the same parser POST /execute uses, so the two endpoints agree on
the spelling, the types and the ranges - a load run declares a stream exactly as
a send does. It was a 400 here until this landed, because a load run's
completion accounting has no place for a response that never ends. What changed
is that a load stream always ends.
Under load a stream is bounded by construction. Both caps are always in
force - the payload's, or the sseMaxStreamDurationMs / sseMaxStreamEvents
settings when the payload names none - and neither can be set to
zero-for-unbounded. That is not tidiness: the load loop is completion-driven
(in_flight() = sent - completed, concurrency refilled per completion), so a
transfer that never completes leaks its slot for the rest of the run.
Reaching a cap is a successful completion, not a timeout and not an error: it is the stream's intended end under load, so it lands in the run's success counts, its latency histogram and its status-code distribution like any other 200. Three other endings stay exactly what they were:
| Ending | Reported as |
|---|---|
A cap in maxStreamEvents / maxStreamDurationMs |
Success, stream.capped incremented |
| The server closing the stream | Success, not counted in stream.capped |
maxResponseBodyBytes exceeded |
Error - a refusal to buffer, unchanged. The event cap bounds how many events arrive, not how large one is |
| The whole-transfer timeout | Error - it sits a grace period past the duration cap, so reaching it means the cap never fired |
Events are counted on the write path by a frame counter that agrees with the
design path's parser about what an event is: a frame carrying no data field
is not one, so comment-only keep-alives do not inflate the tally.
The same count reaches the live frames as the events
arrive (issue #3236): streamEvents, eventsPerSecond and streamsOpen on
every frame, and streamTimeToFirstEvent on gate frames, so a run of long
streams shows its progress before the first one ends rather than zero
completions until then. A single-request streaming run carries them, and so
does a collection load run with a streaming step (issue #3304), whose
streamsOpen counts only its streaming steps' transfers; a run with no
stream, and a design (sequential) collection run, which has no live frames,
carry none of the four.
On a single-request run, stream is refused beside transient (as on a send)
and each cap is refused without stream - a cap on a non-streaming run reads
as a bound the caller expects to apply, and ignoring it is how an unbounded run
gets mistaken for a capped one.
A collection run (scenario) streams the steps whose stored request has
stream set (#3235), and only those. The plan reads the flag off each stored
request, so the run declares nothing: maxStreamDurationMs and
maxStreamEvents are accepted without stream here, range-checked as above,
and bound every streaming step, each falling back to its sse* setting on its
own. A step that does not stream ignores them. A top-level stream is a 400
(invalid_run_config) on a collection run, true or false: it cannot make a
stored request stream or stop one streaming, so accepting it would let a caller
believe it did either. A collection load run sends a streaming step through
the same event loop as a streaming single-request run, so the table above
holds per step: a cap or the server's close ends it as a success, its events
land in the report's stream section, its stored exchange keeps its event
count (so GET /runs/:runId/samples reads its events back), and the step's own timeout (or the run's) bounds only its
connect phase - the whole-transfer timeout is the duration cap plus the 5s
backstop. A load run's natural end waits for the longest streaming step's cap
plus that backstop, or for the run's timeout where that is longer (its
ordinary steps are still bounded by it), before cancelling what is still in
flight. A sequential
(design-mode) collection run sends a streaming step through the single-request
client by the same rules: a cap or the server's close ends it as a pass, its
own timeout bounds only its connect phase, and a POST /runs/:runId/stop
ends the stream in flight rather than waiting out its cap (a stream the server
had not yet answered is a cancelled step). The body is the text/event-stream
bytes, held to maxDesignResponseBodyBytes like any step's (reaching it ends
the stream, with bodyCapped); the step's stored trace carries the parsed
events node (items, totalEvents, eventsTruncated) a load sample's does,
and the run's summary and report gain the same stream section, which its
stream* budgets judge. A duration cap that passes before any status line is a
timeout error naming the cap.
The data rows (a data-driven load run)¶
A single-request run may carry a top-level data array - one flat object per
row - and bind it into the request it repeats (issue #993):
{
"method": "POST",
"url": "https://api.example.com/orders/{{data.id}}",
"mode": "constant_concurrency",
"duration": "30s",
"concurrency": 50,
"data": [
{ "id": "1", "email": "ada@example.com" },
{ "id": "2", "email": "grace@example.com" }
]
}
One row per request sent, claimed off a run-wide cursor that wraps: a run
longer than the set repeats it from the top, so the file bounds which values go
out and never how many requests do - that is the load profile's job. The row a
completion was bound to is recorded as dataRowIndex on every retained result,
and the deferred tests script reads that submission's own row as
pm.iterationData.
Everything else is the scenario path's, because it is the same code: the same
validation (an array of objects, present-but-empty refused, bounded by
maxScenarioDataRows / maxScenarioDataBytes, and a cell nested deeper than
100 levels refused with 'data' row N column 'name' is nested deeper than 100
levels, a row that is not an object and is itself that deep with 'data' row N
is nested deeper than 100 levels, and a data that is not an array with
'data' is nested deeper than 100 levels - all checked right after the body is
parsed, whatever shape data has, before the engine snapshots the payload), the
same {{data.column}}
placement rules and escaping, the same credentials-bind-before-they-are-encoded
order, and the same refusal of a {{data.*}} in an oauth2 config. Every
rejection is a 400 invalid_run_config before the run row exists, so a
refused set leaves nothing behind.
Two differences from scenario.data worth stating:
iterationsis not defaulted from the row count. A load profile already says how long the run is; a collection run without an explicit count takes one pass per row.- The two fields cannot be combined. A top-level
databeside ascenarioblock is a400namingscenario.data- the two bind differently (per submission here, per iteration and shared by every step there), so a payload carrying both would have one of them silently dropped.
Which file the rows came from (issue #2051) rides beside them as two
optional, independent strings: dataFileName, a display name (the app sends
the picked file's name), and dataFileHash, the SHA-256 of the file's bytes as
64 lowercase hex characters. The engine stores both verbatim and opens nothing;
no path is ever stored. Each is a 400 invalid_run_config when it is not a
non-empty string, dataFileName also when it holds a / or \ (a path, not a
name), dataFileHash also when it is not that digest shape, and either one is
a 400 when sent without data (refused, not ignored). A
top-level one beside a scenario block is a 400 naming its
scenario.dataFileName / scenario.dataFileHash counterpart, as data is.
How the client read that file (issue #2540) rides beside them as
dataFileCastNumbers, a boolean: true when the client typed the file's
unquoted numeric cells as numbers (the app's Read numbers as numbers). The
rows arrive already typed and the engine never converts them; it records the
flag because the hash is of the file's bytes and cannot tell two readings of one
file apart. null is absent; any other non-boolean is a 400
invalid_run_config, any value (false included) without data is a 400,
and a top-level one beside a scenario block is a 400 naming
scenario.dataFileCastNumbers, on the same rules as the two strings.
The rows are never persisted: the stored run snapshot records the row count
(dataRowCount) plus the file's dataFileName and dataFileHash when they
were sent, and dataFileCastNumbers: true when the numbers were cast (absent,
never false, otherwise, so a run recorded before the flag reads as text),
never its path or rows, exactly as a scenario manifest does. A cell
that binds travels in the request that carried it, so it is stored with
whatever traces the run retains.
The thresholds block (pass/fail budgets)¶
A run may declare budgets it must meet. The engine evaluates them once, when the
run reaches a terminal status, and the report comes back with a
thresholdValidation section carrying one check per
budget and a verdict. Without the block a run is measured and not judged, and
its report has no such section at all.
{
"thresholds": {
"latencyP50Ms": 20, // ceiling, ms; > 0 and <= 86400000
"latencyP95Ms": 40, // ceiling, ms
"latencyP99Ms": 50, // ceiling, ms
"maxErrorRatePct": 0.1, // ceiling, percent of the run's requests; 0-100
"minThroughputRps": 10000, // floor, completed requests per second; > 0
"maxAssertionFailureRatePct": 0, // ceiling, percent of failed assertions, the worse population; 0-100
"streamTimeToFirstEventP95Ms": 800, // ceiling, ms, streaming runs; > 0 and <= 86400000
"streamEventsPerSecondMin": 200, // floor, events per second, streaming runs; > 0
"failRun": true // a missed budget sets status "failed"; default false
}
}
Every key but failRun is a budget; at least one budget must be present (a
thresholds object holding only failRun is rejected the same way an empty
one is - it names nothing to judge). An unknown key, a non-numeric or
out-of-range budget value, a non-boolean failRun, or an object that declares
no budget is a 400 invalid_run_config naming the field - and, like every
other run-config rejection, it happens before the run row is created, so a
rejected request leaves no trace. A null value reads as absent, the same
rule the flat numeric fields follow.
maxErrorRatePct is measured against every response outside 2xx/3xx plus the
transport failures that never got one - the
one error definition, the same figure
summary.errorRate reports and the live tick streams. A request a Stop
cancelled is in neither its numerator nor its denominator.
maxAssertionFailureRatePct (issue #1497) is measured against two
populations a load run keeps apart (issue #2892). The exact one is every
assert.* element outcome, every required extract.* that found no match and
every pm.test call an inline script made, counted on every completion. The
sampled one is the deferred pm.test replay, run over responses sampled at 1 in
response_sample_rate (default 100) - the same tallies the report's
testValidation shows. That is a sampling period, not a promise about the
count: on a long run the max_response_samples reservoir cap can make the
replayed set sparser than 1 in response_sample_rate. actual is the worse of
the two failure rates, each 0 when its population is empty, so a sampled
pm.test failing half the time beside an inline assertion that never fails
reads 50%, not the fraction of a percent a single blended count would give;
the budget fails when either population crosses it. The check names both
populations, so a reader can see which one the verdict came from:
{ "metric": "maxAssertionFailureRatePct", "limit": 10, "actual": 50.0,
"passed": false, "evaluated": true,
"assertionsExact": { "passed": 2270, "failed": 0 },
"assertionsSampled": { "passed": 12, "failed": 12 },
"sampleRate": 100 }
assertionsExact and assertionsSampled are both written on an evaluated
assertion check, an empty population as {passed: 0, failed: 0};
sampleRate (the period the replay ran at, keep 1 in N) is written only when
assertionsSampled is non-empty. No other check carries these keys, and a
check stored before issue #2892 has none of them: its actual is the old
blended rate and nothing is backfilled. Unevaluated, like a latency
percentile, when the run made no assertion at all - a run with no assert.*
element and no test script is unaffected by declaring this budget - and then
the population keys are absent too, as actual is.
streamTimeToFirstEventP95Ms and streamEventsPerSecondMin (issue #3234)
judge a streaming run's stream section:
timeToFirstEvent.p95 and eventsPerSecond, the same figures the report
prints. Both are unevaluated, and so count toward failed, on a run with no
stream section (one that did not stream, or ran with stream_metrics: false),
because a run that streamed nothing measured neither; a floor read as 0
there would fail for the wrong reason. The time-to-first-event budget is also
unevaluated when no completion delivered a timed event.
Every run mode is judged (issue #1564): a single-request load run, a
scenario load run and a collection (sequential, design-mode) run all
evaluate the same thresholds block against their own numbers and store the
same thresholdValidation shape. A collection run's error rate and latency
percentiles are drawn from the steps it actually sent (a step a script or an
unbound data row skipped counts toward neither), and its assertion tally,
every assert.* outcome and pm.test call of every step it ran, is all
exact: a collection run runs each step's scripts on every send, so its
assertion check carries assertionsSampled at zero and no sampleRate.
Since a script error no longer ends the iteration
(issue #2526), the steps after one are sent and counted too, so the same
collection can report a larger denominator than it did before; stopOnError:
true restores the old population.
custom.<name>.<stat> (issue #1500) budgets a named metric.record /
pm.metrics value - <name> the metric was recorded under, <stat> one of
p50, p95, p99, max (a trend), value (a counter's running total or a
rate's percentage, whichever the name was declared as) or rate (the same
field as value, spelled for a rate metric):
Unlike the fixed keys, this is a dynamic key family: the route checks the
shape (custom. prefix, a non-empty name, a stat from the list above) and that
the value is a non-negative number, not that ttfb2 is a name this run's plan
actually declares - a metric.record on a step the run never reaches, or a
plain typo, is not distinguishable from a not-yet-recorded metric at validate
time. Evaluated the same way an unmeasured latency percentile is: evaluated:
false when this run's collector never recorded that name, counted toward
failed rather than a silent pass. The test is the entry's count (records,
not the total - see customMetrics), so a counter
nothing recorded through is unevaluated while a counter recorded only by zero
is evaluated with actual: 0, which is what lets
{"custom.failures.value": 0} pass a run that saw none (#1937). A counter
never goes negative: pm.metrics.counter throws on a negative or non-finite
increment, and metric.record reports error for one and records nothing.
Every run mode is judged, the same
rule the fixed keys follow (#1564): execute_scenario_run folds
summary.custom_metrics into the same RunSummaryInputs it evaluates
thresholds against for a collection (sequential, design-mode) run, not only a
load run.
The verdict is the run's, not the process's: a run stopped early is judged on
what it measured up to that point, and its status stays stopped whatever the
verdict says. The app says so on a stopped run, under the verdict's counts, with
how long the run went against how long it was planned for. A run that reached
its own end whose config set thresholds.failRun: true and whose budgets it
missed ends failed instead of completed; without the
flag, or on a run that met every budget, a failing budget is reported but
never changes the terminal status. Only a Stop that decided the outcome (one
before the strategy returned) makes a run stopped: a Stop that cuts the
natural-end drain short leaves the run to its own end, so failRun still judges
it (issue #3341, see POST /runs/:runId/stop). The
requests that Stop cut are the run's slowest and are in none of its figures,
so its summary records them as drainCut (#3538) and a reader judges the run
not judged unless a budget already failed it; the stored verdict here is
still the budgets' own.
Each check carries evaluated. A latency percentile needs a timed request
to mean anything, so a run that recorded none (every request was refused
before the wire, cancelled by a Stop or failed before any transfer ran)
reports evaluated: false and omits actual entirely rather than the default
0, which would otherwise read as a measured 0ms and trivially satisfy an "at
most" ceiling. A request that timed out or lost its connection after the
transfer began is timed (see Latency
population), so a run where every request timed out is
evaluated and its percentiles sit at the timeout. An unevaluated check
counts toward failed: a budget the run could not measure was not met. The
error rate is the same: a run that sent no request has no share to take, so
maxErrorRatePct is evaluated: false there (issue #3540) rather than a
clean 0% that passes any ceiling, including 0. The throughput floor has no
such gap - a starved minThroughputRps already fails on its own - so it is
always evaluated: true.
Carried-over budgets (carriedBudgets)¶
thresholds says what a run was judged against, not who chose it. The app
seeds its load dialog's budgets from an earlier run's (or from the SLO
setting), so a budget can reach a run the user never set it for (issue #2195). carriedBudgets is the app's
record of which: an array of the thresholds keys it sent as carried over
rather than set for this run, spelled as they are in that block - a fixed
budget key such as latencyP99Ms, a custom row as custom.<name>.<stat>.
The engine stores the list in the run's config snapshot as sent and echoes it
as the report's
metadata.configuration.carriedBudgets; it never
reads the entries, so it does not check them against thresholds, and the
verdict is computed the same with or without it. Absent or null means none
were carried, and the report then has no such key. A non-array, a non-string
entry, more than 64 entries, or an entry longer than 512 bytes of
UTF-8 is a 400 invalid_run_config naming carriedBudgets, before the run
row exists. MCP's start_load_run does not accept the key: an agent declares
its budgets explicitly, so none of them are carried over.
The elements block (element-pipeline override)¶
A scenario load run's elements block overrides how the element pipeline
runs across every step of the run (issue #1495), without editing the
collection itself.
{
"elements": {
"timers": "asConfigured", // "asConfigured" (default) | "off" | {"fixedMs": N} | {"minMs": N, "maxMs": N}
"scripts": "asMarked", // "asMarked" (default) | "allInline" | "allDeferred"
"includeScriptTime": false, // default false
"seed": 42 // Optional, non-negative integer - seeds this run's RNG
}
}
Every key is optional; an unknown key or an out-of-set value is a 400
naming the field, the same invalid_run_config shape the scenario block's
own unknown-key rule uses, checked before the run row is created.
scriptsdecides whether ascript.pre/script.postelement runs inline (on the producer/completion hooks, before or after the step's own send) or stays deferred to the post-runtestsreplay."asMarked"(the default) reads each element's ownconfig.inline;"allInline"/"allDeferred"force everyscript.*element of the run one way, regardless of its own marking.extract.*andassert.*are unaffected - they always run inline on a scenario load run.includeScriptTimefolds the element pipeline's own elapsed time into a step's recorded latency whentrue, and into the run's latency figures with it (latency, the per-tick percentiles and a stored result'slatencyMs), so the run'smaxis never below a step's (#2792); by default (false) both are the transfer alone. A stored trace'stotalMs, the per-phase timings and theslow_threshold_msdecision stay on the transfer either way.timers(issue #1498) is wired end to end:"asConfigured"(default) runs everytimer.*element's own stored config unchanged;"off"silences everytimer.*element for the run (waitedMs: 0, no sleep);{"fixedMs": N}or{"minMs": N, "maxMs": N}replace everytimer.*element's own computed wait with the same fixed value or uniform range, whatever that element's own config says - "replaced, not merged", the same rulescriptsabove uses.timer.think'sstep.betweenphase now dispatches on a scenario load run too (non-blocking, summed intoVirtualUser::ready_at_ms), so this override reaches load runs as well as the sequential run.timer.pacingandtimer.throughputschedule their wait before that step'sElementContextexists at all (Element::scheduled_ready_delay_ms, see Load paths); every mode reaches them there too, through the run's own copy of the override (SharedScheduleState::timers_override, issue #1620), so a run withtimers: "off"defers neither kind under load and a run with"fixedMs"or{"minMs", "maxMs"}schedules their wait from that value rather than the element's owneveryMs/targetPerMinute.seed(issue #1498) is an optional non-negative integer that seeds this run's RNG, making atimer.thinkelement's gaussian or uniform-random wait reproducible. A scenario load run derives one independent generator per virtual user from this seed rather than sharing one across worker threads. Omitted, the run seeds fromstd::random_deviceas before, and every draw is non-reproducible.
Not reported at the run-summary level: there is no summary.timers
aggregate. What a timer.* element waited is per-step, per-element -
waitedMs on that element's entry in the step trace's elements array (see
The step trace) - not rolled up into
GET /runs/:runId / the completion report's summary object.
Not part of this block: a single-request POST /runs payload's step-level
attachment point is the separate requestElements array below, not this
one - this block is accepted on either run shape (the validator does not
distinguish them), and on a single-request run it overrides what
requestElements declares, the same way it overrides a scenario's stored
elements. The run's own boundary, script.setup / script.teardown, is a
third array again, lifecycleElements, further below.
The requestElements array (a single-request run's own step-level elements)¶
A single-request POST /runs payload's own place to attach step-level
elements to the one request it sends (issue #1594): before this, a
single-target load run ran no element pipeline at all, so the same request's
extract.* / assert.* / timer.think / script.* elements that run in a
design send, a sequential collection run, and a scenario load run's steps
never ran under a single-target load run. An array of element descriptors,
the same shape a request's own stored elements column holds:
{
"requestElements": [
{ "kind": "script.pre", "config": { "script": "pm.request.headers['X-Sig'] = sign()", "inline": true } },
{ "kind": "assert.status", "config": { "in": [200] } },
{ "kind": "script.post", "config": { "script": "pm.test('ok', function () { pm.expect(pm.response.code).to.eql(200); })" } }
]
}
Validated the same way a stored elements column is (Registry::validate
per entry, a bad kind or config a 400 naming the index); id and
enabled are optional, defaulting to a generated id and true. The list may
be a composed one, so an id is unique only within the level that declares it
(the origin kind, scope and id POST /compose stamps; an entry with no
origin is the request's own level), and may repeat across levels, the same
per-level id rule as POST /execute (#3101): a duplicated
collection, or a folder repeated down a chain, repeats its ids. The owner rules
differ: every level here is judged as a request's own list, so a
collection-only kind stays refused (below) where /execute accepts it at a
collection level. A repeat within one level is a 400,
and the Item N in a refusal counts within that level's entries. Refused
outright beside a scenario block, whose steps already carry their own
resolved elements from the plan. This is the field MCP's start_load_run
renames a composed request's chain-then-own elements onto, since POST
/compose answers under the plain elements key and this endpoint's own
elements key means something else (the override block above) - see
mcp.md.
Only the kinds this run shape's own hooks actually dispatch are accepted:
extract.*, assert.*, timer.think, script.pre/script.post - the same
phase-0 set issue #1514 gave the design send (extract.* includes
extract.header). A control.* or metric.* kind or
timer.pacing/timer.throughput is a 400 naming the element by its kind
label and where it was declared (from the collection 'Orders' for a
collection or a folder under it, set on this request, read from the entry's
origin; element '<id>' for an entry that carries none) - not by position, because a
composed list interleaves inherited elements with the request's own (#3050).
It is never silently accepted and left inert: those need per-VU controller and
pacing state (controller_state, SharedThroughputCounters,
pacing_state) this run shape's single-submission model has no equivalent
of, and admitting one without running it would report "ok" in
summary["elements"] for behaviour that never happened. Run a sequence that
needs a controller as a "scenario" instead, where its steps carry that
state. A disabled entry ("enabled": false) is not refused: the pipeline
skips it before its apply runs, so a switched-off pacing timer inherited
from a collection does not block the run. It is still validated like any other
entry, so a malformed config fails now rather than when it is switched on.
A collection-origin script.setup / script.teardown is refused as a
request's own (#3070). POST /compose emits an enabled collection's or
folder's run-boundary scripts stamped origin.kind: "collection", but this
array is validated as a request's own list and Registry::validate refuses the
two kinds there: they belong to the collection's own run (or to
lifecycleElements, below), not to one request's submission. The app's load
dialog and MCP's start_load_run leave them out of the payload they build, so
only a hand-written client sees the 400.
vayu::core::ElementPipeline runs the compiled list per submission, the same
phases a design send uses: script.pre at step.before, extract.* /
assert.* / script.post at step.after. A script.* element runs
inline only when marked or forced. Unlike a design send or a sequential
collection run, a load submission has no persistent per-VU object to defer a
script onto, so a script.pre or script.post element runs inline, per
submission, only when its own config.inline is true or this run's
elements.scripts override (above) is "allInline"; left unmarked with no
override, script.post still runs, but deferred - on the run's completion
replay, the same way a plain tests string used to - while script.pre
simply never runs at all, because there is no pre-request replay to defer it
to. RunContext::script_element_runs_inline is the one place that decision
is made, shared with the scenario load path's own step dispatch.
timer.think's wait is folded into maintain_concurrency's own
backpressure (RunContext::reserve_think_wait) rather than a blocking sleep
on a worker thread, so a request-level timer costs no new thread the way the
scenario load path's per-VU wait does. That is the closed loop only: every
mode but constant_rps. A constant_rps run skips timer.think
(#3541): its pacer sends on a
schedule, so there is no next request for a wait to hold back, and a
reservation would only fill maxInFlight with slots no request holds,
dropping arrivals and inflating peakConcurrency. The element is tallied
skipped in summary["elements"], nothing is reserved, and the report
carries one think_timer_skipped_open_loop warning. The element is not
refused, because an inherited timer would then block load-testing every
request under its collection in the default mode.
A script.pre element's edits reach the wire, and its scope's writes reach
later {{tokens}} in the same submission. When a run's submissions are
copied (its requestElements hold a script.pre, or sit beside data rows, a
token the bind owns or a credential waiting on the scripts; see
POST /runs for the shared-request run that is not), each
submission resolves against a small, request-scoped variable overlay (vayu::http::routes::ScopeOverlay) layered over the run's
flattened base scopes, and the residual-token pass
(resolve_residual_tokens, Request composition) runs
against that view before the transfer - so a pm.environment.set (or a
pm.request edit) an inline script.pre makes is visible to any
{{token}} compose left written on that same request (one it could not
answer, or one it deferred past the script, #2521), the
same guarantee a scenario load run's per-VU overlay gives its own steps.
Nothing shares this overlay across submissions - each one gets its own,
discarded after - which is what keeps many concurrent submissions from
writing through one shared map.
An inline element's pm.info carries the run's request identity (#3460).
bind_submission_identity (load_strategy.cpp) binds the submission's
iteration, its virtual user (1) and its data row (#3124), and the run's
requestId / requestName, resolved once when the run starts by the same
read_run_script_identity (run_manager.cpp) the deferred replay reads - the
payload's own fields, the linked row's name when only an id was sent. A run
started from no saved request reads both as undefined, inline and deferred
alike.
The lifecycleElements array (a single-request run's own setup/teardown)¶
A single-request POST /runs payload's own place to declare
script.setup / script.teardown (issue #1573): it has no collection row to
declare them on, and the elements block above is a per-step override, not a
place to author new behaviour. An array of element descriptors, the same
shape a collection's own elements column holds:
{
"lifecycleElements": [
{ "kind": "script.setup", "config": { "script": "pm.environment.set('token', 'x')" } },
{ "kind": "script.teardown", "config": { "script": "pm.sendRequest(...)" } }
]
}
Restricted by kind to the two elements that dispatch at a run's own
boundary rather than a step's - any other kind is a 400 naming the index
and the kind, not silently ignored or run as if it were one of the two. Each
entry's config is validated against that kind's own schema (the same
Registry::validate a collection's elements column is checked against);
id and enabled are optional, defaulting to a generated id and true.
Refused outright beside a scenario block - a scenario collection already
has a real elements column for this, so declaring both would be two
sources of truth for the same run boundary.
script.setup runs once, before the run's first submission (before
test_start is captured, so its own time is never folded into the run's
duration figures, live or stored: the live stream's elapsedSeconds reads 0
until it ends); a throwing setup, or one that fails a pm.test, fails the
run - Failed, nothing sent, its outcome under the report's
lifecycle.setup - the same as a collection-backed run. script.teardown runs once, after the
last submission settles, and sees pm.info.run (requestsSent,
errorRate, assertionsPassed, assertionsFailed); a throwing teardown is
recorded under the report's lifecycle.teardown and never changes the run's
terminal status. Both read and write the same variable scopes every other
script of the run shares - the environment named by environmentId, and the
collection scope of the request requestId links, when the run links one,
else of the composed collectionId (issue #3461); a bare URL run naming
neither gets no collection scope. Unlike a
collection-backed run, script.setup / script.teardown alone do not make
what a script writes reach the request: the stored values do, through the
start-of-run pass (POST /runs, #3253), but that pass runs
before script.setup, and the residual-token pass (see above) runs only on a
run whose submissions are copied. So a pm.environment.set in script.setup
reaches a later {{token}} only when the run declares requestElements and
its submissions are copied (a script.pre among them, or data rows, a token
the bind owns or a credential waiting on the scripts beside them); a run whose
requestElements only read the response sends the stored value. With
lifecycleElements alone,
pm.sendRequest (external side effects) and the lifecycle outcomes in the
report are the only things observable from this run shape's own
script.setup/teardown. See elements.md for the shared
dispatch mechanism a collection-backed run uses for the same two kinds.
The monitor block (server vitals)¶
A run may name a metrics endpoint on the target, which the engine scrapes for
the life of the run on its own thread. The samples are stored per run and
served by GET /runs/:runId/monitor, streamed live as
monitor frames on GET /runs/:runId/live, and summarised
in the report's monitor section. Without the block nothing is scraped and none
of those three carry anything.
Only a load run reads the block. A scenario payload with no load mode is a
collection run, which has no scrape lifecycle, so it is refused (below) rather
than accepted and never scraped; add a mode beside scenario to scrape.
{
"monitor": {
"url": "http://localhost:9100/metrics", // required; http(s), loopback and private allowed (not Vayu's own ports)
"intervalMs": 1000, // optional, defaults to `monitorIntervalMs`; 250-60000
"format": "prometheus", // optional, default "prometheus"; or "json"
"series": [ // required; 1 to `monitorMaxSeries` names
"node_cpu_seconds_total",
"process_resident_memory_bytes"
]
}
}
format decides how the body is read:
prometheus- the text exposition format. Comment and blank lines are skipped, a trailing exposition timestamp is ignored, and a value that is not a finite number (NaN,+Inf) is dropped. Series are matched by name, and samples sharing a name across label sets are summed, sonode_cpu_seconds_total{cpu="0"}and{cpu="1"}chart as one series. Aseriesentry is therefore a bare name: one holding a{(a label filter such ashttp_requests_total{code="500"}) or whitespace could never match, and is refused (below).json- a flat object of numbers, whereserieslists the keys to read. A key that is absent or non-numeric is skipped. A key may hold any character,{and spaces included.
A name the body does not carry is absent from that sample rather than zero. A scrape that reads nothing at all stores no row and sends no live frame, and the report counts it under one of two causes, because they need different fixes:
- a failure (
monitor.failures) - no 2xx answer: a transport error, a timeout, or a status outside 2xx.monitor.lastErrornames the most recent one's cause. - a no-match (
monitor.noMatchScrapes) - a 2xx answer whose body carried none of the requested names (a mistyped name, or a body in the otherformat). The endpoint answered; what it was asked for is wrong.
Neither fails the run. After five consecutive failures the engine logs once and backs off to twice the configured interval until a scrape is answered; a no-match is an answer, so it ends the backoff rather than extending it. A scrape still in flight when the run ends is cancelled rather than waited out, and counts as neither.
Three of the limits are settings rather than constants: intervalMs defaults to
monitorIntervalMs when the block omits it, the series ceiling is
monitorMaxSeries, and how long a single scrape may take is
monitorScrapeTimeoutMs (see GET /config). All three are read
per run, so a change applies to the next run started - no restart. The interval
bounds are fixed, because a cadence below 250ms measures the scraper rather
than the target and one above a minute records nothing on a short run.
The scrape budget has no field on the block: it is about the endpoint being
scraped, which is the same one run after run, so it lives with the other engine
settings. Left at its default of 0 it tracks the cadence at three quarters of
it - raise it when a heavyweight /metrics renders too slowly for that, and the
cadence stays where you set it.
Loopback and private addresses are deliberately allowed: this is a local tool
scraping the user's own infrastructure. The one exception is every outbound
path's: the engine's own port and the MCP port are refused
(Reserved local ports). An unusable block (no url, a
non-http(s) scheme, no series, more than monitorMaxSeries, an out-of-range
intervalMs, an unknown format, or under prometheus a series name holding
a { or whitespace) is a 400 invalid_run_config naming the field, before
the run row is created.
A monitor block beside a scenario that carries no load mode (absent,
empty or not a string) is likewise a 400 invalid_run_config naming
'monitor'.
A run carrying a targetPolicy is held to it here too: the
url's host must be one the policy allows, or the run is a 400 under
target_not_allowed / target_host_unknown naming monitor.url, before the
run row exists (#3121). The URL is judged as the scrape will send it, so a \
in it counts as the / it is sent as. Loopback and private hosts get no
exemption from a policy; without one, "Loopback and private addresses are
deliberately allowed" above is the whole rule.
The scenario block (collection runs)¶
A run may instead state its work as an ordered collection - the collection
runner's sequence primitive. The block replaces the single request, so a payload
carrying it needs no top-level method / url, and states its iteration count
inside the block rather than through mode / duration / iterations:
{
"scenario": {
"source": "collection", // required; the only accepted value today
"collectionId": "col_123", // required
"recursive": false, // optional, default false - descend into sub-collections
"iterations": 1, // optional; defaults to the data row count, else 1
"data": [ { "user": "a" } ], // optional inline rows; see maxScenarioDataRows
"dataFileName": "users.csv", // optional, only beside data: the file's display name, never a path
"dataFileHash": "<sha256>", // optional, only beside data: SHA-256 of the file's bytes, 64 lowercase hex
"dataFileCastNumbers": true // optional, only beside data: the file's numbers were read as numbers
},
"environmentId": "env_123", // optional, and what {{variables}} resolve against
"stopOnError": false // optional, default false - see Outcomes under Scenario runs
}
The collection is resolved into an ordered, fully composed plan once, before
anything is sent, in the order the sidebar displays top to bottom: direct
requests by requests.order and - with recursive - each collection's
sub-collections and requests as one sibling list, depth-first, a request
running where it sits and a sub-collection's whole subtree where the
sub-collection sits, under the sibling order in Ordering (a
sub-collection first on an order tie). The run follows the render (issues
431, #2535). Each step is¶
composed through the same path POST /compose uses, so a step's request and
its resolved elements (every collection, folder and request level's scripts,
each run in turn and each reported with its level, #2522) are what a Send of
that request would run. A
collection edited mid-run therefore cannot change the sequence underneath
itself, and no execution path re-reads the database for request data.
A valid block answers 202 {runId} and creates a run with
type: "scenario" - unless a load mode sits beside it, which makes it a
scenario load run with type: "load" instead. The
lifecycle is a load run's either way -
the run is registered, streams over
GET /runs/:runId/live, stops through
POST /runs/:runId/stop and reports through
GET /runs/:runId/report - and only the executor
differs. See Scenario runs below for what it does while it
runs and what it leaves behind.
Every rejection is a 400 with error.code: "invalid_scenario", raised
before any run row exists - an empty or oversized sequence is never silently run
as a smaller one:
| Input | Rejected because |
|---|---|
source absent, or anything but "collection" |
The discriminator exists for a future stored scenario; an unknown value must not fall through to the collection path. |
collectionId absent, not a string, or empty |
There is nothing to resolve. The id is echoed back when it names no collection. |
The collection (with recursive applied) has no requests |
An empty sequence is a mistake, not a zero-step run. |
| A step's composition fails | The message names the step index, request name and id. |
More steps than maxScenarioSteps |
The whole plan is held in memory for the run's life; the message carries the count and the cap. |
recursive present and not a boolean |
|
iterations present and not a whole number in 1-2147483647 |
It is read as a count, so 0, a fraction and a string are each a run nobody asked for. |
data present and empty |
A data set that binds nothing is a mistake - omit the field to run without one. |
data not an array, or a row that is not an object |
|
More data rows than maxScenarioDataRows |
The message carries the count and the cap. |
A data cell nested deeper than 100 levels (constants::spec_document::MAX_READ_DEPTH) |
Refused before the row is measured or kept, because both recurse and a cell nested far enough overflows the stack (issue #2362). The message names the row and the column: 'scenario.data' row 1 column 'tag' is nested deeper than 100 levels. The check runs right after the body is parsed and whatever shape data has: a row that is not an object but is itself nested that deep answers 'scenario.data' row 1 is nested deeper than 100 levels, and a data that is not an array, nested that deep, answers 'scenario.data' is nested deeper than 100 levels. A wrong shape within the bound keeps the refusals above. A cell nested exactly 100 levels is accepted. |
A data array larger than maxScenarioDataBytes |
The row count cannot catch a few very large rows, and the engine's general body cap (Request bodies) sits far above this and refuses a whole payload without naming what in it was too large. |
A step carrying a {{data.*}} token in a run sent without data |
Nothing would bind it, so the literal token would be sent. The message names the step and the token. The step's credential fields are scanned as well as its request. |
A step with a {{data.*}} token (or the iteration identity) in its oauth2 config |
The token is acquired against the token endpoint (once, when a load plan is resolved; at the step's send in a sequential run), never bound per iteration, so no iteration exists for a row to reach it. Refused with or without a data set. |
A step of a collection load run with a {{name}} in its oauth2 config that no variable answers (invalid_scenario; a single-request run is refused the same way under invalid_run_config, see Auth pre-flight) |
A load run acquires each step's token once, when the plan is resolved and before any script runs, from the stored values, so the name would reach the token endpoint as written. A script's write to an OAuth 2.0 variable is ignored under load and nothing is re-acquired per iteration (the only change after the start is each step's mid-run refresh). The message names the step and the token (#2521, #2742). A sequential run defers such a name to its step's send instead. |
A step whose OAuth 2.0 token endpoint host the run's targetPolicy refuses |
Judged before the endpoint is posted to. The code is the policy's, target_not_allowed or target_host_unknown, not invalid_scenario (#2521). |
dataFileName or dataFileHash present and not a non-empty string, or dataFileHash not 64 lowercase hex characters |
Stored verbatim as what the run was driven by (issue #2051), so a value that cannot name a file, or a second spelling of one digest, is refused rather than recorded. |
dataFileName or dataFileHash sent without data |
It would describe rows the run never bound - refused, not ignored (issue #1503). |
dataFileName holding a / or \ |
A display name, never a path (issue #2051): a path would be stored and listed back to every reader of the run. Send the file's name alone. |
dataFileCastNumbers present and not a boolean, or sent without data (false included) |
How the client read the file (issue #2540), stored beside its name and hash; on the same rules, so a value that is not an answer, or one describing rows the run never bound, is refused rather than recorded. null is absent. |
A scenario key other than source, collectionId, recursive, data, dataFileName, dataFileHash, dataFileCastNumbers, iterations |
An unrecognised key used to change nothing and still answer 202 (issue #1503) - refused by name so a typo or a knob a future engine reads is never silently ignored. |
A cycle in the collections.parent_id tree terminates the recursive walk rather
than hanging it, exactly as the cascade delete in DELETE /collections/:id does.
Five settings bound a scenario (see GET /config). Four are in
the limits category, which is where a ceiling that rejects an oversized input
lives; maxScenarioStoredSteps is data_retention, because it bounds what a
finished run keeps rather than what one may ask for:
| Key | Default | Range | Effect |
|---|---|---|---|
maxScenarioSteps |
200 |
1-10000 | Largest plan one run may resolve to. The sequence is composed up front and held in memory, and a load-mode scenario allocates a latency histogram per step, so this bounds memory rather than expressing a preference. |
maxScenarioDataRows |
1000 |
1-1000000 | Largest inline data array. The app parses the CSV/TSV/JSON/JSONL file and sends the rows - the engine never reads a file from disk - so this bounds the payload that decision costs. |
maxScenarioDataBytes |
16777216 |
1024-104857600 | Largest inline data array measured in bytes of JSON. The row bound alone does not bound the payload, since one row may hold a megabyte in a single cell. |
| maxScenarioStoredSteps | 5000 | 0-1000000 | Per-step results rows one run stores; 0 stores every step. Steps that did not pass are kept first, successes fill the rest, and what was thinned is reported in the run summary. |
| maxStepsPerIteration | 0 | 0-1000000 | How many steps one iteration may execute before it is cut off. pm.execution.setNextRequest can send an iteration backwards, so a cycle would otherwise run forever. 0 derives the bound from the plan - ten times its step count, never below 100 - so a straight-through iteration can never trip it. |
The two data bounds are also enforced by the app before the run, against the file it is about to parse, so a set this endpoint would refuse is named while the file can still be changed. The file format those rows come from - which extensions are read, the header row's rules, quoting, encoding, and what a CSV cell's type becomes - is the app's contract and is documented once, in Data-Driven Runs. This endpoint only ever receives rows.
Scenario runs¶
A scenario run executes every step of the plan, in order, once per iteration.
Each step is the POST /execute exchange - pre-request script, send through the
environment's cookie jar, test script - so a step behaves exactly as a Send of
the same request does, and the two cannot drift apart.
What carries between steps.
- Variables. The environment, globals and collection scopes are loaded once
at run start, mutated in memory by every step's scripts, and written back
once, when the run ends (through the same diff that keeps a Send from
rewriting a scope no script touched). The collection scope is each step's
own (#3248): the chain from the root collection, through the collection
being run, down to the folder the step's request sits in, that folder the
one a script's
pm.collectionVariables.setwrites, as on a Send of the same request. Each collection is read once, so what one step writes into a folder is what a later step in that folder, or in a folder below it, reads; a sibling folder does not see it. Ascript.setupandscript.teardownread and write the collection that declares them (#3456): the run's lifecycle set is every collection from the root down to the one being run and, on arecursiverun, every folder beneath it, set up root first and torn down in reverse (seelifecycleunderGET /runs/:runId/report). Every collection a script changed is written back to its own row in the one write at the end, which comes afterscript.teardown(#3249): a teardown'spm.environment.set/pm.globals.setis saved with the steps' writes. A load run persists no variable, a teardown's included. - Cookies. The environment's jar, unchanged - so a step that logs in leaves a session the next step sends.
A plan in which anything can write a variable resolves its
{{names}}at each send (issue #2521). The plan is composed once, at run start, and its sequence stays fixed for the run. When any step of it carries an enabled, non-blank element that writes a variable scope before some send - ascript.pre, ascript.post(a test script), ascript.setup, or anyextract.*kind, on the request, a folder above it or the collection; ascript.teardownalone does not count, because it runs after the last send - every step keeps each name a scope answers written, scripted or not, and each iteration resolves them immediately before that step's send, against the scopes as every script and extractor up to and including the step's own pre-request script left them, read through the step's own folder chain (#3248), so a sub-folder's{{name}}in a recursive run is its folder's value. That is Postman's order: a login whose test script or extractor stores a new token is followed by a step whoseBearer {{token}}carries that token, on every run and every iteration, and not the one the environment held when the run started. The same four kinds of name as indeferredVariablesstill resolve at composition, and an OAuth 2.0 config defers only on a sequential run (a load run acquires its token at plan time).A plan with no such element is resolved once, before the first send, exactly as before: a name that already had a value when the run started is fixed for the whole run, which is what keeps a collection edited mid-run from changing the sequence underneath it.
A name composition could not answer (issue #1008) is resolved the same way. Since #1009 that name keeps its braces instead of resolving to
"", so each step resolves it again, immediately before that step's own send, against the scopes as every script up to and including that step's own pre-request script left them - not just throughpm.environment.get(...)and apm.requestedit, though a script can still reach it that way too. That is what lets a step early in the plan fetch a token and a later step'sBearer {{token}}carry it with no script of its own. A step's own request holds one search per field, and a plan where every name was already defined at run start and nothing writes a variable pays that and nothing else.The exceptions are the two reserved namespaces below, which neither pass touches:
{{data.*}}and the{{$vu}}/{{$iteration}}identity (issue994). Composition leaves both alone so the runner can bind them per¶
iteration, and neither is a name any script scope answers either. A bare name the run's
dataColumnsnames travels the same way (issue #1007): composition defers it exactly as it defers{{data.*}}, and the per-row bind substitutes it before the step's pre-request script ever runs - so neither pass sees it unresolved, and neither can answer it from a same-named environment variable instead of the row.
Scripts additionally read pm.info.iteration (0-based), pm.info.vu
(1-based) and pm.info.iterationCount. See
scripting.md for which run shapes report
which.
A run with data binds one row per iteration. Row i % rows binds to
iteration i, and the run's scripts read it as pm.iterationData -
get(name) and toObject(), read-only, and undefined for a run sent without
data. With iterations absent the row count is the iteration count; with
both given the explicit count wins and the index wraps. The rows reach the run's
worker and nowhere else: they are not persisted, and the snapshot records the
row count (dataRowCount) plus the file's dataFileName and dataFileHash
when they were sent, and dataFileCastNumbers: true when its numbers were read
as numbers, never its path or rows. The full contract is in
scripting.md.
{{data.column}} puts the row into the request itself. pm.iterationData
is read after a step's request was built, so it cannot change where the
request goes; the data.* namespace can. A step whose URL, header or body
carries {{data.email}} has it substituted with that iteration's row, per
iteration, immediately before the send. A form-data part's contentType binds
the same way, on a text part as on a file part.
The {{data.column}} spelling is reserved and disjoint from the variable
tiers - not a fourth, higher tier. {{data.id}} and {{id}} are different
names, so a data set can neither shadow nor be shadowed by a global, collection
or environment variable through that spelling, and adding a data file to an
existing collection cannot change what its other tokens resolve to. Composition
(POST /compose, and the plan resolution that shares it) leaves a data.*
token written exactly as it stands for that reason; {{data.}} with no column
after it names nothing and follows the ordinary unknown-name rule instead.
A bare column name is a second, different rule and it is a tier (issue
1007). Postman binds a dataset's columns to bare names, so an imported¶
data-driven collection is written {{username}} rather than
{{data.username}}, and while a row is bound that row's own bare column
names answer above the active environment - see D18 in variable
resolution
for the full ladder and the tradeoff it makes against #402's guarantee above.
Which bare names a bind owns is not global - it is stated per composition, as
the dataColumns field, or filled by the engine itself where
it already knows the dataset (a scenario plan's steps, a single-request load
run, a send carrying one row). A bare name not in that set resolves as an
ordinary variable, exactly as it did before this rule existed; only a name the
set names is deferred by composition the way data.* always was, for the
run's per-row bind (core::apply_data_template) to join through the identical
walk - the same escaping, the same missing-column and null-cell refusals, the
same header rules, for either spelling. There is no second, looser
substitution path for the bare one.
Where a token participates. Exhaustively, and identically for both
spellings: the URL (path and query string alike, so a token in a stored
request's params reaches it once they are joined into the URL), every
header name and header value, the raw body, both halves of
every form field (x-www-form-urlencoded and form-data), and the
credential fields of the request's auth - the bearer token, basic
auth's username and password, and an api key's name and
value. Script text is never interpolated at all (a script reads its row
through pm.iterationData, or through pm.variables for a bare name - see
scripting.md).
The pass runs over the composed text, not the text as it was authored, so a
token that arrived as a variable's value binds like any other: a variable
endpoint whose value is /u/{{data.id}} leaves {{data.id}} in the URL after
composition - it is rescanned since issue #1009, but the data. namespace is
deferred to bind time (issue #1007), so this token survives it - and the data
pass then binds it. That is usable, and it is also why the no-data refusal
below says "or from the variable value it was written into" -
the token it names may not appear anywhere in the request as you wrote it.
{{$vu}} and {{$iteration}} are the second reserved namespace (issue
994), and they bind at the same moment out of the same walk - a field carrying¶
one of each is one string, so both are split once and joined together. They need
no rows behind them: {{$vu}} is the virtual user's own 1-based number in a
scenario run and 1 in every other shape (one request repeated is one user's
iterations, whatever the concurrency), and {{$iteration}} is that user's
0-based iteration, the submission index on a single-request run, and 0 on a
plain POST /execute. A variable named $vu does not answer for the identity,
for the reason a variable named data.id does not answer for the column, and
{{$vus}} is an ordinary unknown $name that keeps its braces. They bind
everywhere a data.* token does, credential fields included (issue #1055):
a credential carrying either name defers its build and is bound before
apply_auth encodes it, on every run shape rather than only on one carrying
rows, because the identity comes from the iteration rather than from a row. A
credential that also holds a name only a variable scope answers takes the row
first and is applied after the pre-request script (#2473), on every send that
runs one (see Authentication). An
OAuth 2.0 config is the exception and is refused by name - its token is acquired
before any iteration exists.
A run binds only what it was given rows for. A POST /runs carrying
scenario.data binds per iteration, one carrying the top-level
data binds per submission, and a
POST /execute carrying a data object binds that one row. A request sent
without rows performs no data pass at all, so a {{data.*}} token in it
reaches the wire as the literal text {{data.id}} - no substitution, and no
warning, since composition leaves the reserved namespace written as it stands by
design. The no-data refusal below is the scenario path's alone: a single request
has no plan to refuse before it starts, so a raw API or MCP caller putting
{{data.*}} into one without rows is asking for the literal braces and gets
them.
Credentials bind before they are encoded. A credentials file behind basic auth is the canonical data-driven run, so a step whose credentials carry a
{{data.*}}keeps them unresolved in the plan and applies its auth per iteration instead: the row is bound first, and only then does the username and password become one base64Authorization, or an api key become a percent-encoded query parameter. Every other step still resolves its auth once, when the plan is composed.OAuth 2.0 is the exception, and it is refused rather than ignored. Its token is acquired against the token endpoint, never bound per iteration, so no iteration exists for a row to reach - a
{{data.*}}anywhere in anoauth2config is a400atPOST /runsnaming the token, with or without a data set. A sequential run acquires a step's token at its send, after the step's pre-request script, so anoauth2config naming a variable the script sets resolves then; a collection load run acquires once at planning and refuses a name nothing answers.
Which columns a collection expects is a separate, declared thing - see
dataSchema under Collections and
Data-driven runs. Declaring it changes no binding
rule; it is what lets the refusal above name the columns, and what the app
checks a picked file against before the run.
What a cell renders as. The CSV/TSV path produces strings unless the file opted into number reading (#2540), so the first row is the ordinary case; a JSON or JSONL file may carry any type:
| Cell | Substituted text |
|---|---|
| String | The string, byte for byte - no quoting round trip |
| Number | As JSON writes it: 7, -1.5 |
| Boolean | true / false |
| Object / array | Compact JSON: {"a":1}, [1,2] |
null |
Nothing - the bind errors instead, see below |
Placement is typed, and that is the point. In a JSON body, a token written inside a string literal produces a string and a token written outside one produces the value's own JSON type:
sends "id":"42", "n":2, "flag":true for a JSON file's {"id":"42","n":2,"flag":true}.
Write "n":"{{data.n}}" instead and the number arrives quoted; that is the
knob, not a bug.
A value cannot break the document it lands in. For a body whose text is a
JSON document - json, jsonrpc, and a graphql body written as the
{"query": ...} envelope - a token inside a string literal binds escaped,
so a cell carrying ", \ or a newline arrives as its own text inside valid
JSON rather than ending the string early. A token outside a string literal is
not escaped, which is what keeps typed placement working. Nowhere else is
anything escaped: a URL, a header, a form field and a text body take the
rendered value byte for byte, and a bare (un-enveloped) GraphQL document is
escaped once, later, when the engine wraps it.
An xml body has quoting rules of its own rather than JSON's, so it gets its
own encoding - decided per token from where in the document that token sits,
because XML has no single escape set the way a JSON string literal does:
| Position | Encoding |
|---|---|
| Element text | &, <, > escaped as entities |
| Attribute value | the above, plus the quote delimiting that attribute (" or ', whichever the author wrote) |
<![CDATA[…]]> |
verbatim - a ]]> in the value is written ]]]]><![CDATA[>, which reopens the section instead of ending it |
A tag or attribute name (<{{data.tag}}>) |
verbatim - no escape is legal in a name |
Inside <!--…--> or <?…?> |
none - the bind is refused, naming the token |
The last row is a refusal rather than an encoding because every candidate is
wrong there: a comment is not sent as content at all, a processing instruction
is markup addressed to the parser, and a value carrying --> or ?> would end
the construct and send a document the author did not write. It errors the step
like a missing column does, for every row alike.
The mode decides this, not the content: a text body holding XML still
takes the cell byte for byte.
A token naming a column the bound row does not carry errors the step before anything is sent, with a message naming the token, the row index and the columns the row does have. Substituting an empty string would send a request quietly pointing somewhere else, which is the failure this namespace exists to remove.
A cell carrying a CR or LF bound into a header errors the same way. A
header line ends at CRLF, so a cell holding ok\r\nX-Admin: true does not put
that text in the header - it ends the header and makes the remainder a header of
its own, forged by the data file. There is no escape for a line break in a
header the way there is for a quote in a JSON body, so the row is refused rather
than encoded around, naming the token and the row. The rule covers a header
name, a header value, and a credential written into a header line (a bearer
token, an api key sent in a header); basic auth's pair and an api key sent in
the query are base64- and percent-encoded before they reach the wire, so they
bind unchanged. JSON and JSONL rows keep native strings - there is no CSV
grammar to have stripped the newline - so this is an ordinary cell, not an
exotic one.
The cell is one of three origins the rule covers, and they share one definition
of what a header may hold. A {{variable}} substituted into a header, or into
a credential written into a header line, is refused by POST /compose with
unsendable_header, naming the variable; every other origin - a script, a
credential typed with the byte in it, an import, a raw POST /execute payload
- is refused before the transfer starts, naming the header. That last gate also
covers a NUL (which truncates the line rather than forging one) and a multipart
part's field name, filename and content type.
Two headers that bind to one name error the same way. X-{{data.h}}
resolving to authorization beside a literal Authorization, or two templated
names resolving alike, would send that header twice where the request's rows
name two different headers - so the row is refused instead, naming the header
as it is written, the name it produced and the row. Two headers written alike
are not this: they are a repeat the author typed and can see, and every row
sends both (issue #2466); this refusal exists only for the rows that produce
one.
A header name a row binds to nothing errors the same way (issue #1095), and
is reported ahead of a collision when a row does both - two names that bind to
nothing collide on a name neither of them has, which is not what the file's
author needs to be told. {{data.header_name}}: acme whose cell is blank would
otherwise send the line ": acme", under a name nobody wrote and with a value
they did mean, once per iteration. The message is the one every layer that can
leave a header nameless shares, with the row in front of it; the column is
inside the header as written, where that wording names it. A name a bind merely
shortens is not this rule - X-{{data.h}} with a blank cell binds to X-,
which is a name a request can carry.
A cell that is present but null errors the same way, naming the token and
the row. It is the same failure one type down - the token says the value comes
from the file and the file says there is none - and writing "" for it would
send {"n": } for a typed placement or a quietly blank field for a quoted one.
A column that is legitimately optional belongs in a script, through
pm.iterationData (see
scripting.md), where null is a value
a branch can read.
A run sent without a data set at all whose plan still carries a data.*
token is refused outright, before any run row exists: nothing would bind the
token, so every iteration would send the literal text {{data.id}}. The 400
names the step and the token, and - when the collection
declares a data contract - the columns it declares, so the
message says which file to run with rather than only that one is missing:
step 1 (request 'Fetch user', id 'req_a') carries {{data.id}}, but this run has
no 'scenario.data' set. ... (declared columns: id, email)
Starting such a collection as a quick smoke check means running it with a data file - a one-row set is enough - because the run this refuses would not have exercised the endpoint either.
Each step execution writes one results row carrying the design-mode trace
plus iteration, stepIndex, stepName, requestId and outcome, and -
for a run with data - dataRowIndex, the row that iteration bound. The step
whose error ended its iteration short of the plan's end also carries
stepsNotRun, defined under Outcomes below; it is absent, never 0, on every
other row. A step whose extractors found nothing carries extractorMisses
(#3053), how many of them did, on the same absent-at-0 terms (the rule is in
Elements). A step whose request still held a {{name}}
when it went to the transfer carries unresolvedTokens (#3248), how many
distinct names, on the same terms: the residual pass answers every name the
step's scopes define, so a name counted here is one nothing defined, sent as
written, never refused. A step refused or skipped before the transfer carries
none. Bodies are
capped by maxTraceBodyBytes; the row count is capped by
maxScenarioStoredSteps as described above.
A step whose scripts said anything additionally carries a scripts node
(issue #724) - the same object and the same four keys
POST /execute returns and a design send stores, so a step's
assertions read the same inside a run as they do on a single send. It is the
only route those results take: a collection run answers 202 long before its
scripts have run, so nothing about a step is ever returned live. A step whose
scripts said nothing stores no node at all. The results.error summary line
("3 tests failed -
Every level's scripts run and every level's results land in that node
(#2522): the collection's, each folder's from the outermost in, then the
request's own, in that order, each testResults and consoleLogs entry
carrying a scope of collection, folder or request (absent on a trace
stored before the field, read as request). A failing pm.test at any level
fails the step, and a script that throws at any level errors it; when the level
that threw is not the request's own, the step error names it - "Collection
pre-request script failed - ...", "Folder test script failed - ..." - where
the request's own throw keeps "Pre-request script failed - ..." / "Test script
failed - ...". When more than one level throws, the first one is reported.
A step of a collection bound to an OpenAPI document additionally carries a
validation node (issue #681) - the same object and the same shape
POST /execute returns - saying whether its response matched
the schema that document declares. Absent for an unbound collection and for a
step that sent nothing. By default the verdict is its own channel and changes no
outcome; failOnSchemaError: true on the run makes a schema failure fail a step
that passed everything else. The run's rollup is
schemaValidation in the report.
Outcomes are passed, failed, skipped, errored and stopped:
| Outcome | Meaning | Effect on the iteration |
|---|---|---|
passed |
The request completed and every assertion held. | Continues. |
failed |
A pm.test assertion did not hold, at the collection, a folder or the request. |
Continues - the request itself completed. |
errored, step |
The step did not run clean: the pre-request or test script threw, at any level (a thrown error, a script timeout, a refused pm.request write-back, a top-level pm.response.to.have.status(...) that did not hold), or the exchange did not complete (a transport failure, a request timeout, a request refused before the wire, a {{data.*}} token the row could not bind). |
Continues with the next plan position, as Postman and Newman do by default. With stopOnError: true it ends the iteration instead. |
errored, flow control |
The runner refused the step's flow control: an unresolved or ambiguous setNextRequest (or control.switch / control.loop) target, or the maxStepsPerIteration cap. |
Ends the iteration, whatever stopOnError says. The next iteration still runs. |
skipped |
A pre-request script called pm.execution.skipRequest(), so nothing was sent. The row carries the request and no response. |
Continues with the next step. |
stopped |
A Stop (POST /runs/:id/stop) or an engine shutdown cut the step short (#3397): its transfer, the late OAuth 2.0 token request ahead of it, or one of its scripts' pm.sendRequest was cancelled, or one of its scripts was ended while it ran (#3460). The row carries the cancelled response (status 0, Request cancelled). |
Ends the run. No later step is sent or stored, and the step is no error: not in errored, failed, stepsNotRun, the status distribution, coverage or the assertion tally. |
Either kind of errored is the same outcome on the row, in the summary's
errored count and on the step frame, with the error in results.error; the
table's split is only about what the iteration does next. An HTTP error status
is not an outcome: a step that answered 4xx or 5xx with every assertion holding
is passed, and the summary's failedRequests counts it. The five outcomes
are disjoint and sum to stepsExecuted, a skipped step included
(passed + failed + errored + skipped + stopped; a summary stored before
3397 has no stopped and reads it as 0). A step that completed before the¶
Stop landed keeps the outcome it earned. A
scenario load run reports the other four under the same
arithmetic and reads a step's flow control the same way: a no-response step
and a thrown inline script are errored (#2947), a step that errored has its
own jump (control.switch, control.loop) dropped, and a jump the run cannot
honour is the errored of the step that set it (#2974). A load run stores no
step rows, so that error's text, the same sentence, is the stepError of a
run warning in the engine log. What differs there is a step that
got no response: on a load run it ends its iteration, so a load run's
errored is not the sum of its steps' noResponse, and iterationsAbandoned
is its iteration-abort count. On a collection run a transport failure
continues the iteration like a script error does, as Postman's and Newman's
runners do by default; a later step that reads a response that never arrived
errors on its own row. A step that errored while the iteration continues has its own flow control
ignored - a setNextRequest, skipRequest or setNextRequest(null) from a
script that then threw is an instruction from code that did not finish, so the
iteration walks to the next plan position (see
scripting.md).
The run's summary also carries the HTTP/2 fallback count (#3262). Every sent
step's trace has httpVersionDowngraded (see POST /execute),
and the runner adds those up into the stored summary's http_version_downgraded,
the key a load run writes, so the report's summary.httpVersionDowngraded is the
same figure in both run kinds. It counts requests, not steps: a step the plan
skipped sent nothing and is never in it, and a request that asked for http2
and got HTTP/1.1 is one for every iteration it ran in. It is written as 0 for
a run that counted and saw none, so only a summary stored before #3262 lacks the
key.
stopOnError is a top-level boolean on POST /runs, default false,
type-checked before the run row is created (null reads as the default, and a
non-boolean is a 400 invalid_run_config naming the field). Set, every
errored step ends its iteration, a transport failure and a script error
alike, which is Newman's --bail shape and what a collection run did before
issue #2526. It
is a collection-run (design-mode) key: a scenario load
run does not read it. It rides the stored snapshot as
sent and is echoed in the report's scenario section, so two runs that differ
only in it never read as the same run.
stepsNotRun counts the plan positions an error cost: when an errored
step ends its iteration, the positions after it that the iteration had not
already attempted. It rides the step row (and the step frame) that ended the
iteration when it is above zero, and the report's scenario.stepsNotRun sums it over the run. An
iteration that ends any other way adds nothing: setNextRequest(null) and a
forward jump are a script's decision, not a loss, and a stop is the user's:
a stopped step adds nothing under stopOnError either.
iterationsCompleted keeps its meaning - an iteration an error ended still
completed.
A run whose steps failed still reaches completed: the outcome of the work is
in the steps, and only the runner itself failing makes the run failed. A stop
ends the step in flight - its send, its late token request and its scripts'
pm.sendRequest all carry the run's stop as their cancel, so it lands within
about a second rather than after a request timeout - and is otherwise honoured
between steps, so a stopped run does not finish the iteration it was in.
An engine shutdown stops an active run the same way.
A step's scripts can redirect the sequence. pm.execution.setNextRequest(name)
runs a named request next instead of the one that follows, setNextRequest(null)
ends the iteration, and pm.execution.skipRequest() (pre-request scripts only)
sends nothing and marks the step skipped. A target that names no step in the
run, or one that two steps share, fails the step by name rather than guessing,
and maxStepsPerIteration above is what stops a cycle. Both refusals end the
iteration whatever stopOnError says, and a step whose script errored has its
redirect ignored. The full contract,
including everywhere the two methods throw, is in
scripting.md.
The stored snapshot carries a step manifest, never the composed plan.
runs.config_snapshot holds the block as validated - with data replaced by
its row count - plus {index, requestId, name, method, url} per step, where
url is the stored, uncomposed one. The composed plan carries resolved
Authorization headers and, for an apikey auth with in: "query", a live key
in the URL; it lives in memory for the run's life and nowhere else.
Controller elements redirect the sequence too (issue #1515). control.if,
control.once and control.throughput skip a step the same way
pm.execution.skipRequest() does; control.switch jumps to a named member the
same way setNextRequest(name) does - one flow-control channel, not two, so
the rules above (an unresolved target fails the step by name, a cycle trips
maxStepsPerIteration) apply identically. control.loop, on a folder, walks
its members a fixed number of times per iteration by looping back to the
folder's first member. See elements.md for the
kind table and every config shape.
control.transaction reports its own percentiles. A folder carrying one
sums every member's own response latency, at microsecond precision, into a
named total per pass, and the run's summary gains
scenario.transactions[] = { name, count, errors, latency: { min, p50, p90,
p95, p99, max } }, omitted for a transaction the run never closed. A pass
closes when the iteration leaves the folder (#3054): after the folder's last
member whether it was sent, skipped by a controller or failed before an
answer, or after any member from which the iteration jumps out of the folder
or ends. So count is one per iteration that attempted a member, and a pass
whose every member was skipped, or that a Stop interrupted, is not counted.
errors counts the passes in which a member was an error by the report's
own definition: no response, a status outside 2xx/3xx, or a failed
assertion.
includeTimers: true (issue #1569) also folds a between-member timer.*
wait into that sum - excluded by default, and always excluded for a wait
after the folder's own last member, which is outside the transaction's span.
elements.md has the full close rule.
The same shape reports on a scenario load run's summary, top-level rather
than under scenario - see below.
Scenario load runs¶
Adding a load mode beside the scenario block runs the same plan as a
load test: concurrency virtual users, each walking the sequence on its own,
closed-loop on the event loop. The absence of mode is what still means a
design-mode collection run, so a payload written before this existed keeps its
meaning exactly.
{ "mode": "constant_concurrency", "concurrency": 50, "duration": "60s",
"scenario": { "source": "collection", "collectionId": "col_1" } }
| Field | Meaning here |
|---|---|
concurrency |
The number of virtual users - what k6 and JMeter mean by it. Each holds its own position in the plan and its own cookies. |
duration |
Wall-clock length, for constant_concurrency and ramp_up. Virtual users keep starting iterations until it is up. |
iterations (top level) |
mode: "iterations" only: total passes over the plan across all virtual users. Distinct from scenario.iterations, which the design-mode runner reads. |
startConcurrency / rampUpDuration |
ramp_up only, as for a single-request run. |
Rejected with a 400 (error.code: "invalid_run_config"), before any run
row exists:
| Input | Rejected because |
|---|---|
mode: "constant_rps" with a scenario |
An open-loop arrival rate over a multi-step sequence is an arrival-rate executor, which Vayu does not implement. Refused rather than silently run closed-loop. |
mode: "capacity" with a scenario |
The search judges one p99 per level and a sequence has one per step, so which of them the knee is measured against is a question the mode does not answer. |
rps / targetRps above zero, on any mode |
It is an open-loop arrival rate, and a scenario run is closed-loop by design: no scenario mode reads it, so it is refused rather than ignored. |
An unknown mode |
maxInFlight is moot and is ignored with a warning: in-flight requests are
bounded by the virtual-user count by construction, so concurrency is the only
knob.
What differs from a design-mode collection run:
- The run's
typeisload, notscenario. It publishesmetricsticks overGET /runs/:runId/live(notstepevents) and reports RPS and percentiles like any load run. - Cookies are per virtual user, empty at the start of each iteration, and the environment jar is untouched. One session shared between 1,000 virtual users is not the thing being measured.
- Variables are each step's own folder's (#3248), as in a design-mode
collection run: the environment and globals the run loaded, and the chain
from the root collection down to the folder the step's request sits in,
each entry as the run's
script.setupscripts left it. All of it is read once, before the first request, so a recursive run sends a sub-folder's{{name}}with that folder's value whether or not the plan carries a script. Ascript.setupandscript.teardownread and write the collection that declares them, from the same lifecycle set a design-mode run uses (#3456; seelifecycleunderGET /runs/:runId/report), so what a folder's setup writes reaches the steps in that folder and the folders below it. Nothing a load run's scripts write is saved. - The element pipeline runs here too, per virtual user (issue #1495).
extract.*andassert.*always run - before the send (step.before) and after the response (step.after). Ascript.pre/script.postelement runs there only when its ownconfig.inlineistrue, or the run'selementsoverride forces it; unmarked, a step's scripts still stay deferred, keyed per step, exactly as before this issue - see the next bullet. Each virtual user writes through its own overlay, never the run's shared scopes, so a name one user's step 1 writes (anextract.json's target, an inline script'spm.environment.set) is visible only to that same user's later steps, never to another user's concurrent one. A collection write stays on the step's own folder (#3248): it answers that user's later steps in the folder and in folders below it, not a step in a sibling folder. Those saved names outlive the iteration that wrote them (#3044): acontrol.oncelogin's extracted token still answers every later iteration of that user. An extractor's miss with nodefaultunsets its name the same way (#3053): for that user alone, a value the run's stored scopes hold included, until the user sets it again. What resets at each iteration boundary is the user's cookies and its run-local scope (pm.variables.set); a bound data row's columns are the new row's.pm.executionstill throws - a script cannot redirect the sequence under load. A controller element can (issue #1515):control.if,control.onceandcontrol.throughputskip a step the waypm.execution.skipRequest()would, counted in the run's summaryskippedkey rather than the0every scenario load run reported before this;control.switchandcontrol.loopjump the plan (issue #1569), resolved the same way a script's ownsetNextRequestwould be and guarded by the samemaxStepsPerIterationcycle limit the sequential run uses.control.throughput'sperUser: falseshares one budget across every virtual user instead of one per user, andcontrol.transaction'sincludeTimersfolds a between-membertimer.*wait into its reported sum - both issue #1569 too. - A script that did not run inline stays deferred, keyed per step. After
the run drains, that step's own post-request script is replayed against the
responses that step produced, and the tallies appear on that step's entry in
the breakdown as
tests(seescenario.stepsbelow). A step with several un-inlined, enabledscript.postelements replays each one as its own script, in order, against every sample (issue #3125): aconstone declares is not visible to the next, while a variable-scope write is. Theirpm.testresults add up, and an element that calls none and does not throw counts as one pass. An inline element runs in its own fresh context during the run; a disabled one never runs and talliesskipped. A step that carries no script, whose script ran inline this run, or whose script never got a sampled response, carries notestsobject at all rather than a row of zeros.
Sampling is keyed per step for the same reason: the run's
max_response_samples budget is split evenly across the steps that carry a
deferred script (floored at one apiece), so the last step of a forty-step
plan is sampled instead of being crowded out by the first. The whole-run
testValidation section still reports the aggregate - it says something
failed, and the per-step tests say where.
- Data rows are claimed from one shared cursor, one per virtual-user
iteration, wrapping when they run out - so two virtual users never start
with the same row while unclaimed rows remain, which is what a credentials
file is for. Once every row has been claimed the cursor wraps and rows are
reused, concurrently: a 10-row file under 50 virtual users, or any
duration-mode run past the row count, has several users on one row at a time.
Size the file to the concurrency if the rows must stay exclusive. Every step
of an iteration binds that iteration's row. scenario.iterations still has no
meaning here: the run repeats until its duration is up, and the row count does
not bound it.
A {{data.column}} naming a column its bound row does not carry fails that
step: nothing is sent, the step's errors count in the breakdown moves, and
the run's error list carries an entry with error_type: "data_binding_failed"
naming the token, the row and the row's columns. It is never substituted with
an empty string. A null cell, two headers binding to one name, and a header
name a row binds to nothing fail the same step the same way.
Every retained result carries dataRowIndex on its trace, which is how
a failure is attributed to a row when no per-step results rows exist. Absent
for a run sent without data.
- A step that got no response ends its iteration (a transport error, or a
step never sent) and its virtual user starts the next one. It is never
stranded. So does a control.switch or control.loop jump the run cannot
honour (a target no step answers to, or one past maxStepsPerIteration), as
on a collection run, with the step that set it errored (#2974). A step that
answered with an HTTP error status (4xx/5xx) counts in its errors but does
not end the iteration: a response arrived, and the next step runs.
- No per-step results rows are stored - one row per step per iteration per
virtual user is what a load run exists not to keep. The report's
scenario.steps breakdown is the per-step record instead:
"scenario": {
"iterations": 480, "iterationsCompleted": 474, "iterationsAbandoned": 6,
"stepsExecuted": 954, "passed": 906, "failed": 30, "errored": 6,
"skipped": 12, "virtualUsers": 50,
"assertions": { "passed": 432, "failed": 30 },
"steps": [
{ "index": 0, "name": "Log in", "requestId": "req_a", "method": "POST",
"executed": 480, "errors": 6, "httpErrors": 0, "noResponse": 6,
"unresolvedTokens": 0, "extractorMisses": 3,
"latency": { "min": 1.2, "p50": 4.0, "p95": 9.1, "p99": 12.4, "max": 30.2 },
"elements": [
{ "id": "el_1", "kind": "extract.json", "name": "Session token",
"origin": { "kind": "request", "scope": "request", "id": "req_a", "name": "Log in" },
"passed": 471, "failed": 0, "missing": 3, "error": 0, "skipped": 0, "deferred": 0 }
] },
{ "index": 1, "name": "Get me", "requestId": "req_b", "method": "GET",
"executed": 462, "errors": 30, "httpErrors": 30, "noResponse": 0,
"unresolvedTokens": 3,
"preRequestScript": "skipped",
"latency": { "min": 0.9, "p50": 3.1, "p95": 7.8, "p99": 10.0, "max": 22.5 },
"elements": [
{ "id": "el_2", "kind": "control.if", "passed": 462, "failed": 0, "missing": 0, "error": 0, "skipped": 12, "deferred": 0 },
{ "id": "el_3", "kind": "assert.status", "passed": 432, "failed": 30, "missing": 0, "error": 0, "skipped": 0, "deferred": 0 }
],
"tests": { "sampled": 20, "passed": 20, "failed": 0,
"console": [ { "level": "log", "text": "user 42 loaded" } ] } }
]
}
This run ended by its iteration count: 6 of its 480 iterations lost their
login to no response and were abandoned there, and the other 474 completed.
Get me was reached 474 times; its control.if skipped 12 of them and 462
ran, 30 of those answered a status its assert.status rejected. So
stepsExecuted is 480 + 474 = 954, which is the 942 steps that ran plus the
12 skipped, and the four outcomes are 906 + 30 + 6 + 12 = 954. Three of the
474 logins answered without a token: the extractor's miss unset {{token}},
so Get me sent it unresolved three times.
iterations is the iterations started, not the iterations asked for, and
three counts account for them: iterationsCompleted (the iteration reached its
last step, or a script ended it with setNextRequest(null) or a forward jump),
iterationsAbandoned (a step that got no response, or a jump the run could
not honour, ended it) and the iterations still running when the deadline or a Stop
ended the run. The last has no key of its own; it is derivable:
iterations = iterationsCompleted + iterationsAbandoned + cut at the end, so the iterations cut at the end areiterations - iterationsCompleted - iterationsAbandoned
That term is 0 for a run that ended by its iteration count, as the example above did (480 = 474 + 6 + 0), and positive for one a deadline or Stop ended mid-iteration: 1,150 started, 1,140 completed and none abandoned is 10 cut. The app's Steps tab shows it as "Iterations cut short" beside the other two.
One histogram is allocated per plan step at run start, which is the other thing
maxScenarioSteps bounds.
A step's errors follows the run's one error definition (issue #2124): a
status outside 2xx/3xx, or no response at all. It is the sum of two disjoint
counts. httpErrors is the responses that arrived with a 4xx or 5xx;
the step's latency includes them, and the iteration carries on to the next
step. noResponse is the executions that got nothing back (a transport
error, booked under status 0 like the run's own distribution, or a
data-binding failure that sent nothing); these end the iteration, as a jump
the run could not honour does, and a refused jump is in neither count: it is
an outcome (below), not a request error. A
noResponse execution whose transfer ran (a timeout, a reset, a DNS or TLS
failure) is also in the step's latency, so a step that times out reports its
timeout in p99 and max; one that never reached the wire (a data-binding
failure, a refused header, a skip) adds a count and no duration. The step's
histogram follows the same population as the run's, and includeScriptTime
applies to a failed step as it does to an answered one (issue #2384), folding
the same pipeline time into the run's latency as into the step's, so the run's
max is never below a step's (#2792).
At the top of the section, passed, failed, skipped and errored are the
collection run's outcomes (Outcomes under Scenario runs,
2824), counted per step execution and disjoint. A load run has no stopped:¶
a step its Stop cancelled is in no count at all (#2136). errored is an execution that
got no response, one whose inline script.pre or script.post threw (a
thrown error, a script timeout, a refused pm.request write-back, an inline
pm.execution call; #2947), or one that set a jump the run could not honour
(#2974). A throw outranks a failed assertion and a skip, and a refused jump
outranks every other outcome, as on a collection run. The no-response kind and
the refused jump end their iteration; a throw does not, and only drops the
step's own jump, so a script bug changes the load the target receives only
where the step that threw also asked to jump. errored is therefore not the
sum of every step's noResponse: the iteration-abort count is
iterationsAbandoned. failed is one whose response arrived and in which an
inline assertion did not hold (an assert.* element, a required extract.*
miss, an inline script's pm.test), counted once however many failed in it.
skipped is one a controller (control.if, control.once,
control.throughput) stopped before the wire, and passed is the rest. An HTTP
error status no assertion rejected is passed: the step's httpErrors and the
report's summary.failedRequests count it. stepsExecuted is every step
reached, a skipped one included, and a step's executed is every execution of
it that was not skipped (a skipped one whose script.pre threw, or whose
control.loop repeat was refused, is in it as errored, and adds nothing to
noResponse or the latency), so two identities
hold:
passed + failed + errored + skipped = stepsExecuted- the sum of
steps[].executed, plusskipped,= stepsExecuted
A deferred script's tests replay after the run against sampled responses, so
they fail and error no step here; they are the step's tests and the report's
testValidation. A run stored by engine 0.45.0 or earlier keeps the definition
it was written under: failed was the sum of every step's httpErrors, and
passed was stepsExecuted less failed and errored, its skipped steps
included. Nothing rewrites a stored run.
assertions (#2820) is the run's exact assertion population,
{ passed, failed }: every assert.* outcome, every required extract.* miss
and every inline script's pm.test call, counted on each completion. It is the
figure a maxAssertionFailureRatePct check reports as assertionsExact. It
counts assertions where failed above counts step executions, so an execution
that failed three assertions is one failed step and three
assertions.failed. summary.errorRate stays HTTP-only: a run whose every
assertion failed against 200s reads an errorRate of 0, a non-zero
assertions.failed and every asserting step failed. The deferred replay of an
un-inlined script is the sampled population (the step's tests, the report's
testValidation) and is never in it. Absent, never {0, 0}, for a run that
made no such assertion, for a sequential collection run and for a run stored
before the field existed. The report's top-level assertions (#3537) carries
it as exact, beside the sampled replay, the errored element executions and
the failed teardowns.
tests is the step's deferred validation - a script that did not run inline
this run - and is absent for a step whose script ran inline instead
(its outcome is in elements), asserted nothing, or drew no sample - "no
assertions" and "no failures" are different answers. Beside its
sampled/passed/failed it carries console? and consoleDropped?
(#3127): what that step's replayed scripts logged, as [{level, text, count?}],
the first 10 distinct lines across the step's samples, each cut to 500 bytes,
kept whatever the script's verdict and with count when it was logged more
than once (absent means once), and how many occurrences a full list turned
away.
The list is the step's own, so a line two steps both log appears under each;
both keys are absent when the step's replay logged nothing (consoleDropped
also when nothing was turned away).
elements (issue #1495) is the step's per-element tally,
{ id, kind, name?, origin?, required?, passed, failed, missing, error,
skipped, deferred } one entry per compiled element that ran at least once
this run (an id a collection's element and the request's own share is two
entries, each with its own counts and origin) - absent for a step with
no elements or none that ever ran, the same convention tests follows. Each count is one outcome word of the
sequential trace (#3051): passed is ok, and failed, missing (an
extractor that found nothing, or a metric.record with nothing to read) and
error (an element that could not run its check, a script that threw) are
counted apart. name is the element's own label and origin the level it was
composed from, each present only when the element carries one; required is
present, as true, only for an extractor whose config sets it, and it is what
makes that element's missing a failed step. deferred (issue #2144) counts a
script.post element left to the replay above: it does run, later, and its
assertions are the step's tests. skipped counts every other skipped
outcome: a disabled element, an un-inlined script.pre (no replay to go to), a
controller's skip, an optional extract.json over a body it could not
read, and an inline script.* the run's Stop cut short, its pm.sendRequest
cancelled (#3371) or the script itself ended (#3460), whose tests and throw are
then counted nowhere.
A script.pre or script.post that ran inline also says why it failed and
what it logged (#3127), since a load run keeps no trace to read it from:
{ "id": "el_4", "kind": "script.post", "passed": 0, "failed": 0, "missing": 0,
"error": 480, "skipped": 0, "deferred": 0,
"messages": [
{ "kind": "error", "text": "Error: boom", "count": 480 },
{ "kind": "test", "text": "status is 201: expected 200 to equal 201", "count": 480 }
],
"console": [ { "level": "log", "text": "saw 200", "count": 470 },
{ "level": "warn", "text": "slow body" } ],
"consoleDropped": 37 }
messages lists the errors the script threw (kind: "error", a timeout
included) and each failing pm.test as name: message (kind: "test");
console lists its console lines with their level (log, info, warn,
error). Each list holds the first 10 distinct entries the run produced, in
the order first seen, however many executions repeated one, and each text is
cut to 500 bytes on a character boundary, ending in ...[truncated]. An entry
produced more than once carries count, how many times (the first included);
count is absent on an entry produced once, so the common case and a row
from an earlier engine read the same. The two lists fill apart, so a script
that logs on every iteration cannot crowd out why it failed.
messagesDropped / consoleDropped count the occurrences a full list turned
away (a repeat of a dropped entry counted each time; a repeat of a kept one
counts on that entry's count instead), so a list without its dropped count is
the whole set of distinct entries. Every one of the four keys is absent
when it would be empty or 0, so a row from an earlier engine reads the same. A single-request
run's summary.elements rows carry the same keys. The run export
(POST /export/run-report) leaves all four out.
transactions (issue #1515), a sibling of steps rather than a member of
it - a control.transaction spans a folder, not one step:
"transactions": [
{ "name": "checkout", "count": 480, "errors": 0,
"latency": { "min": 8.1, "p50": 14.2, "p90": 22.0, "p95": 26.5,
"p99": 33.0, "max": 55.4 } }
]
One entry per declared control.transaction name that closed at least once
this run, allocated up front from a scan of the plan - never discovered
mid-run - so recording into it, like every other controller here, takes no
lock. count and errors follow the collection run's rule (#3054): a pass
closes when the virtual user's iteration leaves the folder, including an
abandoned iteration, and errs when a member got no response, answered
outside 2xx/3xx or failed an inline assertion.
unresolvedTokens (issue #1503) counts, per step, how many of its executions
sent a {{token}} composition the residual-token pass still could not answer
- issue #1495 added a real resolution attempt here (against the executing
virtual user's own scope overlay, see elements.md),
but the load path's rule is unchanged: never refused, only counted, so a name
still unanswered (or a header-name collision the attempt itself produced)
goes on the wire regardless. preRequestScript is "skipped" for a step
whose script.pre did not run inline this run and absent otherwise - a step
whose script.pre did run inline reports its real outcome in elements
instead, never both. Neither unresolvedTokens nor preRequestScript ever
fails the run by itself; both also feed the top-level warnings array below.
extractorMisses (#3053) counts the step's extractions that found nothing and
so unset their variable, across every virtual user and iteration; it is absent
at 0. A miss is filed under its element's missing too (or skipped, for an
optional extract.json that could not read the body), and a miss a default
answered is neither: the rule is in
elements.md.
Response:
tests, postRequestScript(s) and preRequestScript(s) are refused
outright (refuse_legacy_script_fields), the same rule POST /execute,
PUT /requests/:id and PUT /collections/:id already applied since issue
1514 - a payload carrying any of the five names (a real value, not null)¶
is a 400, before the run row exists. The name it points a caller at
depends on the shape: requestElements for a single target (this endpoint's
own elements means the run-level override, not a script source, and
pointing there would send a caller straight into a second refusal), plain
elements for a scenario (its steps read theirs off the bound collection's
stored elements, which no field on this payload can name more precisely).
POST /runs was the one route that still read the old names on a single
target - it had nothing else to run a script through until its own element
pipeline existed - and issue #1594 closed that gap: requestElements
(above) is a single target's own script slot now, the same way a scenario's
steps already read theirs off the plan's compiled elements. A caller still
sending tests gets the same refusal every other route already gives;
MCP's start_load_run never sends it - it folds the
agent-facing postRequestScript / tests argument into a script.post
entry of requestElements client-side (see
mcp.md).
A script.pre element only reaches the wire when it is marked to. The
ad-hoc preRequestScript(s) field itself is refused (see above, same as
tests) - a pre-request script only ever rides as a stored script.pre
element now, on either run shape. Unmarked (config.inline unset, no
elements.scripts: "allInline" override), it never runs - there is no
pre-request replay to defer it to, unlike script.post - so a request that
signs itself in one is sent unsigned. Since issue #1503 this is no longer
silent on the scenario shape: a step whose request carries an un-inlined
pre-request script reports preRequestScript: "skipped" on its
scenario.steps entry, and the run's warnings array carries one line
naming how many steps did. The single-target shape reports the same fact
differently (see requestElements above): an un-inlined script.pre
element's own entry in summary["elements"] counts every submission under
skipped (never deferred, which is only for a script.post the replay
runs) instead of a separate warning line.
Accepted ranges. The numeric config is range-checked before the run row is
created, so a rejected request leaves no pending row behind. A violation is
a 400 whose error.code is invalid_run_config rather than the per-status
default, and whose message names the offending field and why the bound exists:
| Field | Accepted | Rejected because |
|---|---|---|
success_sample_rate |
1-100000 |
It is a sampling period (keep 1 in N), used as counter % rate. A 0 was a division by zero that killed the daemon mid-run. |
response_sample_rate |
1-100000 |
Same modulo, same crash. |
max_response_samples |
0-1000000 |
Each retained sample holds a full response body, and the vector is reserved up front; a negative value casts to ~1.8e19. |
max_response_sample_bytes |
0-1073741824 |
The whole-run budget for those bodies, held in memory for the run and its retention window. The count cap above bounds the store only for a target whose bodies are small - at 1 MiB each, 1000 samples is ~1 GB. 0 retains no sample that has a body. Defaults to the maxResponseSampleBytes setting. |
max_success_results |
0-1000000 |
Each retained record holds a serialised timing breakdown, and the store is reserved up front. 0 means unlimited. |
max_slow_results |
0-1000000 |
Same store, same reserve, separate budget. 0 means unlimited. It caps the slow traces kept, never the report's slowRequests.count, which counts every slow completion. |
slow_threshold_ms |
0-86400000 ms |
0 disables outlier capture; a negative threshold would mark every completion an outlier and fill the slow store with the whole run. |
max_sample_body_bytes |
0-104857600 |
A captured body is copied on the completion callback, so the cap bounds hot-path work. 0 keeps headers and metadata and no body. Defaults to the maxSampleBodyBytes setting. |
max_sample_bytes |
0-1073741824 |
The whole-run capture budget; every byte under it is held in memory until the run flushes. Defaults to the maxSampleBytes setting. |
max_exemplar_results |
0-100000 |
Each retained exemplar holds a captured exchange. 0 means unlimited. |
phase_histograms |
boolean | Per-run override for the phaseHistograms setting. false skips the bank entirely: the run's report carries no timingBreakdown.phases, its avg*Ms fall back to the retained trace sample, and its live gate frames carry no cumulativePhases. |
save_timing_breakdown |
boolean | Read as a bool inside the run-context constructor, which threw on a string after the row was written - the same stranded-pending failure duration had. |
capture_response_bodies |
boolean | Same read, same constructor, same failure. |
concurrency |
1-10000 |
Connections are eagerly pre-allocated per worker before any traffic flows, so -1 (a natural "unlimited" guess) allocated until malloc failed. |
startConcurrency |
1-10000 |
The ramp is seeded with this many in-flight requests before the first duration check, and it is read as a size_t, so a negative start is ~1.8e19 of them. |
maxInFlight |
1-1000000 |
It is a pending-request ceiling read as a size_t, so -1 or 0 removes the backpressure the field exists to provide instead of tightening it, and an open-loop run against a slow target then accumulates in-flight requests for its whole duration. The ceiling is not the concurrency guard: that one bounds an eager per-worker connection pre-allocation, while this bounds a counter that pre-allocates nothing, and the engine's own default - max(targetRps × 10, 1000) - reaches 500,000 at the load dialog's 50k RPS maximum, so a lower bound would refuse ceilings the engine picks for itself. |
timeout |
1-86400000 ms |
A transfer that never times out never completes, leaving the run stuck running and unstoppable. Absent or null, the run uses the defaultTimeout setting, as POST /execute does (#2798). In a scenario run, sequential or load, it is what a step whose stored request states no timeout of its own sends with; a step that states one sends with its own (#2937), and fetches and refreshes its OAuth 2.0 token under it too. It also bounds the run's other OAuth 2.0 token fetches (the pre-flight's, and each step's at plan time and every mid-run refresh) and is the default timeout of a pm.sendRequest from any script of the run: a sequential run's step, setup and teardown scripts, and a load run's inline step scripts, script.setup / script.teardown and deferred tests script (#2833, #2841). Latency percentiles and max saturate at one hour (3600000 ms): a longer completion is counted there, not dropped (#2790). |
duration |
string, positive, optional unit (ms|s|m|h) |
A JSON number threw out of the run-context constructor after the row was written, stranding it pending forever behind an opaque 500. |
stepDuration |
string, positive, optional unit (ms|s|m|h) |
capacity only, and read by the same parser duration is - so it is gated by the same rule rather than by a second copy of it. |
rampUpDuration |
non-negative, optional unit (ms|s|m|h); a JSON number is seconds; 0 is an instant ramp |
Read by ramp_up only, but checked in every mode, like duration. It was not checked here at all, so "10sec" created a row that went running and then failed. Checked by asking the run-time reader itself, so it accepts exactly what the ramp will read - zero and a JSON number included, both of which duration refuses. |
iterations |
1-2147483647 |
An iterations run stops on its request count alone, read as a size_t, so -1 was ~1.8e19 requests and a run that never ended until stopped. The ceiling is the one scenario.iterations has. |
rps / targetRps |
0-1000000, fractions allowed |
The open-loop arrival rate per second; 0 asks for none. The ceiling is the highest RPS cap the app and MCP settings can be raised to. constant_rps needs one of the two positive, and every other mode refuses a positive one - see below. |
stream |
boolean | Accepted since streaming under load landed; read through the same parser POST /execute uses. A non-boolean is a 400 rather than a silent buffered run the caller would wait forever for. Refused on a collection run, either value: there a step streams when its stored request does (#3235). |
maxStreamDurationMs |
1000-86400000 ms |
Streaming only - refused without stream on a single-request run; on a collection run accepted alone and applied to the steps whose stored request streams. Defaults to the sseMaxStreamDurationMs setting. |
maxStreamEvents |
1-10000000 |
Streaming only - refused without stream on a single-request run; on a collection run accepted alone and applied to the steps whose stored request streams. Defaults to the sseMaxStreamEvents setting. |
stream_metrics |
boolean | Whether the run feeds the per-completion event and time-to-first-event histograms, and, on a single-request streaming run, its live event tally. false leaves the report's stream section out entirely rather than zeroing it, and the live frames' stream keys with it. Run-config only - there is no engine-wide setting beside it, because the cost is paid only by runs that stream. |
sloMs |
1-60000 ms |
capacity only. A non-positive budget has no edge to find, and one past a minute is longer than the transfers any realistic run measures. Matches the app's own clamp on the p99 threshold setting. |
carriedBudgets |
array of at most 64 strings, each at most 512 bytes of UTF-8 |
Stored in the snapshot and echoed in every report, and nothing downstream reads the entries, so these bounds are the only ones the list gets. See Carried-over budgets. |
An absent field, or an explicit null, is always accepted - every one of
them has a default. The route erases every top-level null before anything
reads the config, so a null runs exactly as the absent key would and the
stored config snapshot carries none (#1893); it used to pass this check and
then throw in the run's own reader, after the row existed. The ceilings are
crash guards, not policy: each client caps itself far lower (the load dialog
offers concurrency ≤ 1000; the MCP start_load_run tool has a
user-settable cap in Settings).
The defaults an absent field takes are the run_config::DEFAULT_*
constants in engine/include/vayu/core/constants.hpp: duration 60 s for a
constant or ramp-up run, concurrency 100 for a constant or ramp-up run and
10 for an iterations run, iterations 1000, rampUpDuration 10 s, startConcurrency 1. A
capacity run's duration defaults to its own 300 s search deadline instead.
timeout is the exception: it defaults to the defaultTimeout setting (30 s
unless changed in Settings), read when the run starts, for a single-request
and a scenario run alike. A scenario step's own stored timeout (#2937) wins
over both for that step's transfers. A pm.sendRequest keeps the run-level
value, except from a sequential run's step scripts, which take their step's
timeout as a Send's scripts take the Send's. None of them is written to the stored snapshot; only
what the body carried is, so a replayed snapshot that carried no timeout
takes the setting in force at its own start.
A rate belongs to constant_rps, in both directions. Both checks sit in
validate_run_config (check_constant_rps_rate and
check_rate_only_on_constant_rps, routes/execution.cpp) and answer a 400
with error.code invalid_run_config; rps is read first, and targetRps
when rps is absent or 0.
- A
modeofconstant_rpswith neither field positive is refused. It used to run the closed-loop path at the default concurrency while the stored config and the report still saidconstant_rps(#1893). - Any other
modewith either field positive is refused, naming the field and the mode (#2396). A rate used to switchconstant_concurrencyto open loop and to give every other mode's event-loop workers a token bucket ofrate ÷ workers, so a ramp reported its own throttle as latency, while the config and the report still named the declared mode. An unrecognisedmodeis held to this too.0asks for no rate and is accepted on every mode. - A body with no
modeisconstant_rps, as the executor reads it: it may carry a rate, which paces it open-loop, and without one it holdsconcurrencyin flight closed-loop, as it always has.
The executor chooses by mode as well (open_loop_rate in load_strategy.hpp):
a rate that reaches a closed-loop mode without passing this route, in a stored
config, does not open the loop. No mode throttles the event loop's workers
with a rate of their own: a constant_rps run is paced by its pacing thread
alone (#2801).
One field is rejected by presence, not by range: transient. It is
POST /execute's no-run-row flag (issue #382) and has no meaning here, because
a load or scenario run is the row it creates - the run id is what this
endpoint returns, and the live stream, the report and the scenario step store
are all keyed by it. Ignoring the flag would leave a caller believing the run
left nothing behind while it wrote the largest trace the store holds, so a
present transient (true or false) is a 400 with error.code
invalid_run_config. An explicit null is absent, as everywhere else here.
The sample rates are additionally clamped to ≥ 1 inside the metrics collector, so the modulo cannot divide by zero even for a caller that bypasses this route.
What a run stores, and for how long. A completed request is recorded in the aggregate counters always; whether its detail survives is decided by three independent budgets:
| Budget | Filled by | Bounded by |
|---|---|---|
| Sampled timing traces | 1 in success_sample_rate completions, only while save_timing_breakdown is on |
max_success_results |
| Slow-request traces | any completion at or past slow_threshold_ms, regardless of save_timing_breakdown |
max_slow_results (the traces only: the slow count is an aggregate counter) |
| Response samples (post-run test scripts) | 1 in response_sample_rate completions |
max_response_samples, and max_response_sample_bytes |
| Per-status exemplars (captured responses) | the first three completions of each distinct status code that no other budget already stored | max_exemplar_results |
None of these budgets bound the report's timingBreakdown.phases: the per-phase
histograms are fed by every completion and hold counts rather than records, so
the phase distribution, and the avg* fields read from its means, are the
whole population no matter how hard the stores above thin. Only a run without
the bank falls back to averaging the sampled subset.
Two properties are worth relying on. An outlier never consumes a sampling
slot: a run whose target degrades does not silently stop sampling ordinary
traffic because everything became slow. And each store is a reservoir - past
its bound a later record displaces a uniformly chosen incumbent instead of being
refused - so what a long run retains describes the whole run rather than its
first few seconds, and sampling in
the report says how many records that thinning cost.
The exemplar budget is the one exception to the reservoir rule, and deliberately so: an exemplar that gets displaced is not an exemplar, so past its bound a later candidate is refused and counted rather than evicting an incumbent.
It is also the last budget consulted, not the first. A completion that is already an outlier stays charged to the slow budget and a sampled one stays charged to the sampling budget - claiming an exemplar never moves a record out of the store that wanted it, because the first few completions of a status code are often exactly where a run's outliers are. What the exemplar claim decides is whether the response body is captured, which is independent of which budget pays: a completion that is both sampled and a claimed exemplar is stored in the sampling budget and keeps its body.
Response capture. capture_response_bodies (boolean, default true) decides
whether the retained samples carry their response headers and body. On by default
is only defensible because capture is failure-and-outlier-shaped rather than
uniform - errors, slow outliers and the per-status exemplars, never the 1-in-N
slice - so a healthy run captures a handful of exchanges. Set it to false and
the collector is byte-for-byte what it was before capture existed: no gate is
consulted, no exemplar is claimed, nothing is copied, and no rows are written.
What is captured is read back with
GET /runs/:runId/samples and described in
result_bodies.
Shutdown refuses new runs. Once the daemon has begun draining its run
workers, POST /runs answers 503 with the message Engine is shutting down rather
than accepting a run nothing will ever execute. The window is small - the HTTP
server stops before the drain begins - but it is not empty, and a request
already in a handler when the drain starts must not be able to spawn a worker
past it (see RunManager::shutdown). The row the route had already written is
marked failed first, and so is the row of a run that throws while starting
(answered 500, naming the error): no answer but a 202 leaves a pending row
behind (#1893).
A run row the database cannot write is a 500. A busy or locked database, a
full disk or an I/O error while recording the run is the engine's failure, not
the payload's, so POST /runs answers 500 Couldn't create the run record.
The app retries a 5xx and treats a 4xx as a verdict, so a momentary lock no
longer reads as a refused request (#2319).
Auth pre-flight. When auth.mode is oauth2, the run route resolves the
token before creating the run and warms the cache for the workers. An
unauthorizable config is rejected up front with 409 (interactive sign-in
required) or 400, carrying the /oauth2 error codes and, when the token
endpoint answered, its reply inside the error object as
POST /oauth2/token carries it (providerStatus,
providerError, providerErrorDescription, #3201), so a bad token never
surfaces as a silently-failed run. A load run acquires once, before any script,
from the stored values (a script that sets an OAuth 2.0 variable has no effect
under load, and nothing is re-acquired per iteration), so an oauth2 config
still holding a {{name}} when the run starts (one that nothing defines, or one
posted without being composed for a run with deferDynamicVariables) is a
400 invalid_run_config naming it (a collection load run's step is
invalid_scenario, see Scenario runs); and a targetPolicy that refuses the config's
token endpoint is a 400 under the policy's code, before anything is posted.
Concurrency model. constant_concurrency, ramp_up, and iterations are
closed-loop: the engine holds in-flight requests at a target (concurrency,
or the ramp curve from startConcurrency to concurrency) - when a request
completes, another is issued. Throughput is a result (concurrency ÷ latency),
not an input. constant_rps is open-loop: it dispatches at targetRps
regardless of how fast responses return. The mode chooses the loop; a rate is
constant_rps's field alone (see above).
maxInFlight. A hard cap on concurrent in-flight requests. It applies
only to constant_rps (the open-loop rate mode), where it bounds how many
requests may be outstanding before the engine drops new ones; default
≈ max(targetRps × 10, 1000), accepted range 1-1000000. That range holds
the default formula across the whole advertised RPS span (50k RPS → 500,000),
which is why it is not the concurrency guard - a ceiling of 10,000 would
reject explicitly what the engine already does implicitly. For the closed-loop
modes the concurrency target is the in-flight bound, so maxInFlight is
ignored there. It is not what bounds a catch-up burst: when the pacing thread
stalls (a host sleep, a blocked thread), its next tick sends what the schedule
owed up to 100 ms past the instant the tick was due
(MAX_CATCH_UP_BACKLOG, core/load_pacing.hpp) and skips the rest (#2911).
Skipped requests are never sent and are counted as skippedRequests, apart
from the maxInFlight drops, with stalledMs the schedule time they cover
(skippedRequests ÷ targetRps). What the tick does send still passes the
maxInFlight headroom, and nothing meters it per worker (#2801). Ordinary
timer jitter is far inside the window and is caught up in full at any rate.
Durations. duration and rampUpDuration take a string holding a number
with an optional unit: ms, s, m, h, matched as a whole suffix
("500ms" is half a second, not 500 minutes); rampUpDuration also takes a
JSON number of seconds. A bare number is seconds - "60" == "60s" - which
is also how the MCP duration cap reads the field. Fractions are allowed
("1.5s"), case and spacing are ignored ("30 S"). A value the engine cannot
read - an unknown unit, a non-number, a negative - is a 400 with error.code
invalid_run_config naming the field, before the run row exists, rather than
being silently replaced by the default (see Accepted ranges above).
constant_rps is time-bound, and its shortfall is recorded. Request k
(counting from 1) is owed at k / targetRps, so nothing leaves at t = 0 and,
when targetRps × duration is whole, the last request is owed at the deadline
itself. Each tick submits floor(targetRps × elapsed since the start) minus
what it has already taken, so a rate above 1000 is delivered as asked rather
than floored to a multiple of 1000, and a late tick owes what the ticks it
swallowed would have, sending up to the catch-up window above and skipping the
older backlog (skippedRequests). Requests that come due while in-flight is at
maxInFlight are dropped at that instant, not deferred: the run ends at its
wall-clock duration, and droppedRequests (in the run summary and per-tick
metrics) carries what the rate owed but could not issue. sent + skipped +
dropped is therefore exactly floor(targetRps × duration), the run's
requestsExpected (200 req/s for 20 s: 4000; 33.3 req/s for 3 s: 99), for a
run that reaches its deadline. A product that is whole in decimal is read as
whole even where binary lands just below it (0.57 req/s for 100 s owes 57).
Capacity semantics. capacity is the one mode whose target is not a
function of elapsed time. It holds startConcurrency for stepDuration, judges
the level, and then steps up by 25% (at least +1) while the level stayed inside
its budget. A level's p99_ms is the percentile of every completion at the level
after its first three live ticks, which measure the transition to the new
target, read from one histogram; it is not a mean of 100 ms window percentiles,
which a level with a periodic pause would pass. Its rps is the mean throughput
over the same ticks, and its error_pct the share of the requests completed over
them that were errors, by the one definition every surface reports (a status
outside 2xx/3xx, or no response; a Stop-cancelled request is neither). Its
samples is the count of completions that histogram held; a level of only
refused connections is judged on its errors with samples 0 and a p99_ms that
measured nothing. A level breaches when its p99 exceeds sloMs or its
error share exceeds 1%
(constants::capacity::ERROR_RATE_PCT, no run-config knob): a target answering
fast 503s is not sustaining the level. The search stops - and names the reason
in the report - after two consecutive breaching judged levels (one
breaching measurement re-measures the same level rather than ending the
search): slo_exceeded when the last one's p99 is over sloMs,
errors_exceeded when its p99 is inside sloMs and only its error share is
over the limit. It also stops when two step-ups buy under 5% more throughput
(plateau; the report then names the level where throughput stopped growing as
saturation*, which is lower than maxHealthy*, the last level tried), when
concurrency is reached (cap_reached), when duration runs out
(deadline), or when the operator stops the run before the search has ended
(stopped); a Stop that arrives only after the search ended on its own leaves
the reason it had (issue #3341).
An omitted duration on a capacity run defaults to 5 minutes, not the
60 seconds every other mode falls back to: this mode walks a level every
stepDuration, so a minute is a dozen levels and a search that almost always
ends deadline rather than finding anything. Any client enforcing its own
duration ceiling has to account for that per-mode default rather than assuming
one number - the MCP tool's cap does.
The search steers by what the metrics thread publishes each live tick rather
than sampling the collector itself, so it takes nothing away from what GET
/runs/:id/live streams. A level in which no request was timed (latencySamples
0, percentiles null on the frame) and no error was counted is not judged and
stays open: reading it as "answered instantly" would climb straight past the
limit. A request that timed out is timed (see
Latency population), so a level of nothing but timeouts
has samples, is judged, and reports a p99 near the timeout - the level fails its
latency limit, which is the right verdict. A refused connection records no
latency but is counted, so a level of nothing but refusals is judged too, at a
p99 of 0 and an error share of 100%, and fails its error limit. A level is
also not judged until it has counted at least one completion: the error share
is read from status counts that can trail the latency samples by a tick, and
judging before they arrive would read a failing level as error-free.
capacity is rejected on a scenario run with a 400: the search judges one
p99 per level and a sequence has one per step.
Ramp semantics. ramp_up interpolates linearly from startConcurrency to
concurrency over rampUpDuration, then holds concurrency for the rest of
duration. A startConcurrency above concurrency is a valid descending
ramp. If duration is shorter than rampUpDuration, the run stops partway up
(or down) the curve. A run whose duration equals rampUpDuration reaches
concurrency at the end of the ramp, with no hold after it: when the run's
time is up, the controller refills once more to the target its last instant is
owed, so the peak does not depend on when it last woke (#2913). That refill
sends only what the last target it refilled toward was below the end target:
it does not replace requests that completed after the run's time was up, so a
run already at its end target (a flat ramp, a ramp shorter than duration, a
descending ramp) sends nothing once duration has passed (#3545).
Response bodies are capped. A load-run request reads at most
maxResponseBodyBytes (Settings → Data & retention, default 32MB) into memory.
Every in-flight request holds its own body, so an uncapped one multiplies by
concurrency; a response past the cap fails that request rather than being
buffered. It is reported like any other transport failure - statusCode: 0
with an errorCode of INTERNAL_ERROR and a message naming
maxResponseBodyBytes - and the truncated prefix is kept as the body. Design
mode (POST /execute, and each step of a collection run) has its own cap and
its own answer: maxDesignResponseBodyBytes, also 32MB, reached by a send
that keeps what it read and reports bodyCapped: true on an otherwise ordinary
response. It sends one request at a time, so the concurrency argument above
does not apply to it - what does is that the body crosses to the app and is
held there as well, and that failing a response the user asked to see would be
the wrong trade where showing them the first 32MB of it is not. Neither setting
reads the other: raising the load cap does not change what a Send reads.
A script's own fetch (pm.sendRequest) is a third read, and it takes the
bound of the path it runs on: the design bound in a Send's or a collection
step's scripts, the load bound in a load run's deferred tests script, which
runs once per sampled response. It refuses at that bound rather than keeping a
prefix, on either path, because nothing on the object it hands the script could
say the body was cut - see
scripting.
Wire method and body. A body is sent with whatever method the request
names: a GET carrying one stays a GET on the wire (Elasticsearch-style
search bodies work), where it previously went out as a POST. The one
combination that cannot be sent is HEAD with a body - curl's HEAD
support drops the body - so it is refused rather than silently changed:
statusCode: 0, errorCode: INVALID_METHOD, and a message saying so. This
holds identically for POST /execute and POST /runs.
Failed requests still report timing. A transfer that fails (timeout,
connection refused, capped body) carries whatever curl measured before it
failed - wireMs, the phase breakdown, and bytes/throughput counts - instead
of reporting zeros. No phase (dnsMs, connectMs, tlsMs, firstByteMs,
downloadMs) is ever negative: tlsMs is 0 for plain HTTP and for a reused
keep-alive connection rather than the negative value it used to store.
Metrics & Statistics¶
What counts as an error¶
A load run counts a request as an error when its response status is outside
2xx/3xx, or when it got no response at all - a transport failure (a timeout, a
refused connection, a DNS or TLS failure), recorded under status code 0. A
3xx is a success. The count is derived from the run's status-code distribution
(vayu::count_status_failures, issue #2124), so every surface reports the
same number: the live tick's totalErrors / errorRate, the stored tick's
requests_failed / error_rate, the stop response's summary.errors /
summary.errorRate, the report's summary.failedRequests /
summary.errorRate, the maxErrorRatePct
budget and pm.info.run.errorRate.
Each of those count surfaces also splits the errors in two, HTTP errors (a response came back, with an error status) and No response:
| Surface | HTTP errors | No response |
|---|---|---|
Live tick (GET /runs/:runId/live) |
httpErrors |
noResponse |
Stored tick (GET /runs/:runId/metrics) |
http_errors |
no_response |
Stop response (POST /runs/:runId/stop) |
summary.httpErrors |
summary.noResponse |
Report (GET /runs/:runId/report) |
summary.httpErrorRequests |
summary.noResponseRequests |
A request POST /runs/:runId/stop cancels before it is answered is not an
error (issue #2136), whether the Stop landed while the run was sending or cut
its natural-end drain short (issue #3341). It got no outcome from the target, so it is counted on
its own, as cancelled, and is in no other count: not the total, not the
status-code distribution, not either half above, not the error rate. A healthy
target stopped mid-run therefore reads errorRate 0 however many requests
were in flight. The surfaces that carry it:
| Surface | Cancelled |
|---|---|
Live tick (GET /runs/:runId/live) |
cancelled |
Stored tick (GET /runs/:runId/metrics) |
cancelled |
Stop response (POST /runs/:runId/stop) |
summary.cancelled |
Report (GET /runs/:runId/report) |
summary.cancelledRequests |
The cancelled requests of a drain a Stop cut are also counted once more, as
drainCut: {cancelled} (issue #3538): on the stored summary, the report's
summary and the load row's resultSummary, and only there, never on a run a
Stop stopped or one the Stop cancelled nothing from. They are the requests that
outlived the sending window, the slowest and the hung, so leaving them out of
every figure leaves the run judged on its fastest answers: a reader treats such
a run as not judged once no budget failed it
(verdict). They are still not errors.
So totalRequests is the requests that got an outcome,
successfulRequests + failedRequests, and every request the run sent is in
exactly one of totalRequests and the cancelled count. Only a Stop's
cancellation is exempt. When a run reaches its natural end and no Stop has been
requested, a request still in
flight after its effective timeout (the run's timeout, else the
defaultTimeout setting) plus a 2s grace is cancelled too, except in a
streaming run, whose bound is its maxStreamDurationMs plus grace (the 5s
stream backstop plus the same 2s, issue #2834), so a stream still within its
cap is never cut. A collection run with a streaming step waits for whichever
of the two bounds is longer (issue #3235). A non-stream request cancelled there never answered: it stays
an error, under status code 0, and its stored error record carries
error_type cancelled (errors.types in the report).
A request libcurl re-sent on a new connection is not an error either
(issue #2799). When the server drops or refuses a kept-alive connection after
reading a request and before writing a byte of the answer (an idle timeout, a
per-connection request cap, an HTTP/2 refused stream), libcurl replays the
request on a fresh connection on its own; no option turns that off short of
giving up connection reuse. The replayed request is one request with one
outcome: counted once in totalRequests and the status-code distribution, a
success or an error by the status of its last attempt, and with a latency that
covers both attempts. What the target saw is not hidden: each replay is
counted in the report's summary.connectionReplays and raises the run's
connection_replayed warning, so the target received
totalRequests + connectionReplays requests. A non-idempotent request (a
POST) may have run twice there.
Latency population¶
A load run's latency figures all describe one set of requests: every request
whose transfer ran, answered or not. That is a response of any status
(a 4xx or 5xx included) and a request that failed after the transfer began,
where the duration is the time until it gave up (a timeout is about its
timeout; a reset, a DNS or TLS failure and a body over the byte cap count
the same way). The set feeds the report's latency block (p50 to p999,
max), the live tick's windowed latencyP50Ms / latencyP95Ms /
latencyP99Ms, its per-second secondP*Ms and cumulative cumulativeP*Ms,
the stored ticks' latency_p*_ms, avgLatencyMs and avgQueueWaitMs, the
trailing-window means (windowAvg*Ms live, window_avg_*_ms stored), the
exports, and the
latencyP50Ms / latencyP95Ms / latencyP99Ms budgets.
The mean is the sum over the set divided by the set's size, so it agrees
with the percentiles and the max. It is not divided by totalRequests.
Left out, because they have no duration to report:
- a request a Stop cancelled (
cancelled), and a request cancelled at a run's natural end after its effective timeout plus the grace (a streaming run'smaxStreamDurationMsplus grace), which is an error with no duration; - a request refused before the wire: one dropped at the
maxInFlightcap (droppedRequests), an invalid URL or an unsendable header, a residual{{token}}or file-rule refusal, a data-binding failure. An invalid URL includes one libcurl itself refuses before it resolves or connects (a URL it cannot parse, such as a space sent as typed with Send URL without encoding on, or a scheme it guessed for a URL naming none) (#2412).
So a run where 5% of requests hit a 2000 ms timeout reports a p99 and max
near 2000 ms, and a latencyP99Ms budget below that fails it. totalRequests,
errorRate, httpErrors, noResponse and cancelled do not depend on this
set. The per-phase histograms of the timing breakdown
stay answered-only: a request that failed has no connect, TLS or first-byte
split to report. A scenario step's histogram follows the same rule as the
run's.
Where libcurl reports the failure, the test is whether the transfer reached
the network, not which error it ended with. A reply libcurl cannot read comes
back with the same code as a refused URL, but after a real hop, so it is
timed. A redirect to a scheme the engine does not send and an unparsable
redirect Location are the engine's own refusals, reported by the engine
rather than libcurl; the hops before them were answered, so they are timed
too. So are a DNS failure, a refused connection, and a client
certificate or CA file libcurl cannot read: libcurl reads those files during
the TLS handshake, after the TCP connect, so that failure has a duration. (A
client certificate whose file is already unreadable when the run resolves its
transport is dropped there, with a logged error, and the request goes out
without it.)
A stored error row carries the same duration (#2412): its latencyMs in
results[], the Samples tab, and the results.latency_ms column hold the
time until the transfer gave up, so a request that timed out at 2000 ms is
stored at about 2000 ms. A request with no duration (refused before the wire,
or cancelled at a run's natural end) is stored at 0. The row has no other
way to say "no duration", and 0 can also be a real reading under a coarse
clock, so the two cannot be told apart from a stored row; a load run stored by
an engine before #2412 holds 0 for every error. That bounds one report: a
run whose summary holds no latency (a failed run that wrote no summary, or
one the engine died under, whose summary is rebuilt from its last tick and
flagged summary.partial) is reported from its stored rows alone, and there
every stored row, a 0 included, is in the percentiles and the mean, which
divides by the rows stored rather than by this population. A run that finished
on its own reports from its summary, which this does not affect. Those two
reports write no latency block at all (#2938), so none of this reaches a
reader for them.
The sequential collection runner follows the same population, with two differences:
its latency block is computed exact nearest-rank over every sent step's duration
rather than from an HDR histogram, and a run in which no step sent stores a count of 0
and the report omits the block (issue #2389).
GET /runs/:runId/metrics¶
Paginated historical time-series (JSON) for a run's charts. The response is
always JSON - any format query param is ignored.
Query parameters:
- limit - max records per page (default 5000, invalid/≤0 falls back to 5000, capped at 50000).
- offset - skip N records (default 0, negative floored to 0).
- maxPoints - return the whole series as at most this many ticks
(capped at 50000; anything but a positive integer is treated as absent).
limit and offset are then ignored. See
Downsampling with maxPoints.
Per-tick rows carry the latency percentiles of their second
(latency_p50_ms / latency_p95_ms / latency_p99_ms, snake_case): every
100 ms window since the previous row merged as one histogram before the
percentile is read (issue #2385), so a stall anywhere in the second is in its
row. They sit alongside rps/throughput/concurrency/status codes, so the
history view can rebuild the percentiles-over-time chart, the
response-time-vs-concurrency scatter, and the capacity-breakpoint / saturation
stats from stored data. The live tick that wrote a row carries the same three
figures as secondP50Ms / secondP95Ms / secondP99Ms. A row stores no
sample count, and a second with no completion has none of the three keys
(issue #2386), the frame's secondSamples 0 and null percentiles: absent
rather than null because the run export types
them as numbers. Rows an engine older than issue #2386 stored hold 0 for
such a second, and rows older than issue #2385 hold the last 100 ms window of
their second instead.
Response:
{
"data": [
{
"timestamp": 1234567890,
"elapsed_seconds": 10.5,
"requests_completed": 1500,
"requests_failed": 5,
"http_errors": 5,
"no_response": 0,
"cancelled": 0,
"current_rps": 150.5,
"current_send_rate": 151.0,
"window_avg_in_flight": 6.7,
"window_avg_latency_ms": 44.8,
"window_avg_queue_wait_ms": 0.3,
"current_concurrency": 100,
"send_rate": 150.0,
"throughput": 149.5,
"backpressure": 0,
"error_rate": 0.33,
"dropped_requests": 0,
"skipped_requests": 0,
"stalled_ms": 0,
"bytes_sent": 48000,
"bytes_received": 1920000,
"status_codes": { "200": 1495, "404": 3, "500": 2 },
"status_seconds": [ { "second": 10, "span": 1, "counts": [149, 0, 1, 0, 0] } ],
"latency_p50_ms": 38.5,
"latency_p95_ms": 95.1,
"latency_p99_ms": 12.0
}
],
"pagination": { "total": 1, "limit": 5000, "offset": 0, "hasMore": false, "returned": 1 }
}
requests_failed is the producer's own error count, written into the tick at
write time, by the one error definition and from
the same status-code snapshot as that tick's status_codes; http_errors and
no_response split it. cancelled is the requests a Stop cancelled so far,
outside all three (issue #2136); a tick stored before that issue has no
cancelled key. It is not derived at read time from error_rate and
requests_completed any more - that derivation depended on the order the EAV
rows came back in, and reported 0 failed requests for every bucket of every run.
A tick an engine older than issue #2124 stored has no http_errors /
no_response, and its requests_failed counted no-response failures only.
current_rps and current_send_rate are completions and dispatches per
second over the trailing window ending at the row's tick (issue #2393):
at least the last second, divided by the window's actual span (one second
plus up to one tick interval), and until a run has a second of ticks,
everything since its first tick. window_avg_latency_ms and
window_avg_queue_wait_ms are the mean latency and queue wait of the
latency population that completed in the same window,
null when nothing did. window_avg_in_flight is the mean number of
requests in flight over the same window (issue #2821): the time requests
spent in flight during the window, divided by its span (issue #3567). A
request is in flight from its submission to the event loop until it
completes, its queue wait inside the generator or libcurl included, and it
counts for every part of the window it was open in, so requests open across
the whole window with none completing read their count, and a request longer
than the window never reads above one. A virtual user in a timer wait
(timer.think, timer.pacing, timer.throughput) has none in flight, and
neither does a request refused or skipped before it reached the event loop (a
maxInFlight drop, a data-binding failure, a step a controller skipped). A
request a Stop cancels after submission was in flight until the cancellation.
With no think time it equals the virtual user count. It is a number, 0 for a
window with nothing in flight, never null. Before issue #3567 the same key
held the latency the window's completions carried divided by its span, which
read 0 while a request longer than the window was still open and spiked when
it completed; rows stored before the change keep that value under the same
key.
The live frame of the same tick carries the same five values as currentRps,
currentSendRate, windowAvgInFlight, windowAvgLatencyMs and
windowAvgQueueWaitMs. current_concurrency and backpressure are
instantaneous: see the live frame's activeConnections and backpressure
below, which they equal. A run whose virtual users wait
in step aliases them between 0 and the user count, which is what
window_avg_in_flight answers instead. send_rate and throughput are cumulative:
requests sent and completed since load start, divided by the time since load
start, so they flatten a change of rate the window shows within a second. A
tick stored before issue #2393 has none of the three new keys, and its
current_rps divided the completions since the previous row by the time
since it. A tick stored before issue #2821 has no window_avg_in_flight.
status_seconds (issue #2866) is the seconds the row's gate closed, each with
the responses that completed in it, by class: second counts from load
start (the clock elapsed_seconds counts from), span is 1, and
counts is [2xx, 3xx, 4xx, 5xx, error], where error is a response with no
status (code 0) or a code outside 200-599. A second is closed 250 ms after
it ends, so a row usually holds one second, two when its gate's cadence crosses two
second ends, and [] when none closed since the last gate. Across a
run's rows the seconds run on from 0, one entry each, and a second in which
nothing completed is an entry of zeros. Each response is counted by the clock
it completed at, not by the tick that read it, so counts[i] / span is a
class' rate that a batch landing near a tick does not move; the difference of
two rows' status_codes counts what landed between their ticks instead. The
live gate frame of the same tick carries the same entries as
statusSeconds. The second still open when the run
ends is stored nowhere, and the seconds that close after the last row ride the
final live frame only. A tick stored before the issue has no status_seconds.
A missing run returns 404 with the message Run not found.
Storage. Each data[] entry is one stored row of metric_ticks - the
engine writes the tick object once, at write time. Two things follow:
- Pagination is tick-aligned:
limit/offsetcount ticks, sopagination.totalis the number of ticks (not rows), and a page boundary can no longer return a tick with half its fields zeroed. elapsed_secondskeeps counting across pages, since it is stored with the tick: the seconds since load start, the same reading the live frame of that tick carries aselapsedSeconds(issue #2881). No tick is stored before load start, and the first stored tick reads between0and about1.0(the 1 Hz gate counts from the metrics thread's start, so after a setup script it can land anywhere up to one interval after load start). A run an engine older than that issue stored counts from its first stored tick instead, so its first tick reads0, about one second behind the live clock.
A run with no ticks returns 200 with an empty data array - only a run that
does not exist is a 404.
Downsampling with maxPoints¶
Without maxPoints the answer is exactly the paged series above (issue #2547
adds no key to it). With it, the engine reads every stored tick and answers in
one response:
- If the run has at most
maxPointsticks, every tick comes back unchanged. - Otherwise each run of
ticksPerBucket = ceil(total / maxPoints)consecutive ticks, in stored order, is folded into one; the last bucket may be shorter, and a one-tick bucket is that tick unchanged.
The envelope gains two top-level keys on this path only:
{
"data": [ ... ],
"pagination": { "total": 86400, "limit": 2000, "offset": 0, "hasMore": false, "returned": 1964 },
"bucketed": true,
"ticksPerBucket": 44
}
pagination.total is the stored tick count, limit echoes maxPoints,
returned is the number of data entries and hasMore is always false.
bucketed is false and ticksPerBucket is 1 when the series already fit.
Most tick fields are cumulative (a run total or a rate over the run so far), so a folded tick is its bucket's last tick, with a few keys replaced:
| Field | Folded value |
|---|---|
timestamp, elapsed_seconds |
The last tick's |
requests_completed, requests_failed, http_errors, no_response, cancelled, dropped_requests, skipped_requests, stalled_ms, bytes_sent, bytes_received |
The last tick's (run totals) |
error_rate, send_rate, throughput |
The last tick's (run-long rates) |
status_codes, custom_metrics |
The last tick's (cumulative maps) |
latency_p50_ms, latency_p95_ms, latency_p99_ms |
The max over the bucket, its worst second |
current_concurrency, backpressure |
The max over the bucket |
current_rps |
The mean over the bucket's ticks |
current_send_rate |
The mean over the bucket's ticks (#2393) |
window_avg_in_flight |
The mean over the bucket's ticks (#2821): each covers about its own second, so this is the bucket's mean in flight |
window_avg_latency_ms, window_avg_queue_wait_ms |
The mean over the bucket's ticks that carried a number, null when none did (#2393) |
status_seconds |
Every entry of the bucket's ticks merged into one (#2866): the first entry's second, span the seconds the entries cover and counts summed per class, so counts[i] / span is still responses per second; [] when the ticks closed no second |
| Any other key | The last tick's |
The latency fields are never averaged: each row's percentile is of its own
second, so the bucket's max is an upper bound on the bucket's percentile,
not an estimate of it, and a one-second spike survives into the bucket that
holds it. A second with no completion carries none of the three keys
(issue #2386) and so takes no part in the max: a bucket has them only when one
of its seconds completed something. A bucket of rows an engine older than
issue #2386 stored reads 0 only when none of its seconds completed anything,
which is what those rows store for such a second. Rows an engine older than
issue #2385 stored hold the last 100 ms window of their second instead, and
the max is then taken over those windows. A key no tick in the bucket carried
(http_errors on an older row, custom_metrics on a run that recorded none)
is never added.
Only GET /runs/:runId/metrics and GET /runs/:runId/monitor
(the same parameter, folded differently)
downsample. The run-report export
(POST /export/run-report) and the MCP
get_run_timeseries and get_run_monitor tools read the raw rows.
GET /runs/:runId/monitor¶
Paginated server vitals scraped during the run - the samples the
monitor block collected. Same
{data, pagination} envelope and the same limit / offset rules as
GET /runs/:runId/metrics, so one pagination reader covers both.
Query parameters:
- limit - max records per page (default 5000, invalid/≤0 falls back to 5000, capped at 50000).
- offset - skip N records (default 0, negative floored to 0).
- maxPoints - return the whole series as at most this many samples
(capped at 50000; anything but a positive integer is treated as absent).
limit and offset are then ignored. See
Downsampling the monitor series.
Its own endpoint rather than extra keys on the tick objects: that key set is the
/metrics contract, and these samples land on the user's scrape cadence rather
than the tick cadence, so they do not line up row for row.
Response:
{
"data": [
{
"timestamp": 1234567890,
"series": { "node_cpu_seconds_total": 3.75, "process_resident_memory_bytes": 1048576 }
}
],
"pagination": { "total": 1, "limit": 5000, "offset": 0, "hasMore": false, "returned": 1 }
}
timestamp is wall-clock Unix ms - when the engine scraped, not an elapsed
offset - because the scrape starts with the run while a tick's
elapsed_seconds counts from load start, after any script.setup; a stored
tick carries the same wall clock, so joining the two series onto one timeline
is what timestamp is for. A series the target did not
report in that scrape is absent from its series object rather than zero.
The two fields are read off different clocks, which is why they can disagree.
timestamp is wall time, so it moves when the host's clock is adjusted, while
every elapsed figure the engine reports (elapsed_seconds here, and a run's
duration and rates) is measured on a monotonic clock that an NTP step or a
manual clock change cannot move. Over a run that spans an adjustment, the
difference between two timestamp values is therefore not exactly the
difference between their elapsed_seconds; the elapsed pair is the one that
measures how long the run actually took.
A run that configured no monitor returns 200 with an empty data array; only
a run that does not exist is a 404. Samples are deleted with the run, like
every other child row.
Downsampling the monitor series¶
maxPoints here is the same contract as
on /metrics (issue #2611), read from the
same monitor_samples rows in stored order (by timestamp, then insertion):
- Without it the answer is exactly the paged series above; no key is added.
- With a series of at most
maxPointssamples, every sample comes back unchanged andbucketedisfalse. - Otherwise each run of
ticksPerBucket = ceil(total / maxPoints)consecutive samples is folded into one (the key keeps the tick series' name, though a bucket here holds samples); the last bucket may be shorter, and a one-sample bucket is that sample unchanged.
The envelope is the one the tick series answers with: pagination.total is the
stored sample count, limit echoes maxPoints, offset is 0, hasMore is
false, returned is the number of data entries, plus bucketed and
ticksPerBucket on this path only.
A folded sample is {timestamp, series} like any other:
| Field | Folded value |
|---|---|
timestamp |
The last sample's |
each series.<name> |
The max over the bucket's samples that carried it |
The max keeps a one-scrape spike in a gauge (cpu, memory, a queue depth) that a
mean would flatten, and for a monotone counter it equals the last reading. A
name no sample in the bucket carried is never added to the folded series, so
a gap in the target's reporting stays a gap; a non-number value is skipped.
The MCP get_run_monitor tool does not pass maxPoints and reads the raw
samples.
GET /runs/:runId/live¶
Stream live metrics for a run via Server-Sent Events, replayed from a retained
in-memory tick topic. The engine produces one wire-ready metrics tick per
liveTickIntervalMs (default 100ms) into a per-run buffer; this endpoint
replays that buffer from offset 0 (or, for a reconnecting client that names
a resume point, from the frame after it) and then tails new ticks until the run
finishes, ending with a complete event. Because the topic is retained for
liveRetentionMs (default 60000ms) after completion, a client that connects
late - even after a sub-second run has already finished - still receives the
full series. There is no attach race.
Events:
event: metrics
id: 0
data: {"runId":"...","timestamp":1234567890,"elapsedSeconds":10.5,
"totalRequests":1500,"totalSuccess":1495,"totalErrors":5,"errorRate":0.33,
"httpErrors":5,"noResponse":0,"cancelled":0,
"currentRps":150.5,"currentSendRate":151.0,
"sendRate":150.0,"throughput":149.5,
"activeConnections":100,"backpressure":0,"phase":"sending","droppedRequests":0,
"skippedRequests":0,"stalledMs":0,
"avgLatencyMs":45.2,"avgQueueWaitMs":0.4,
"windowAvgInFlight":6.7,"windowAvgLatencyMs":44.8,"windowAvgQueueWaitMs":0.3,
"latencySamples":15,"latencyP50Ms":38.5,"latencyP95Ms":95.1,"latencyP99Ms":156.7,
"cumulativeP50Ms":36.0,"cumulativeP95Ms":90.2,"cumulativeP99Ms":160.4,
"bytesSent":48000,"bytesReceived":1920000,
"requestsSent":1500,"requestsExpected":0,
"status2xx":1495,"status3xx":0,"status4xx":3,"status5xx":2,
"statusCodes":{"200":1495,"404":3,"500":2}}
event: complete
data: {"event":"complete","runId":"run_1234567890","status":"completed"}
status is the run's own terminal status - completed, stopped or failed -
and it is what tells a client which of the three happened while the run is
ending, rather than after the stored report has been fetched (issue #1415).
complete is sent only once the run has written that status (issue #2140): the
last tick can land while the run is still finishing - flushing results,
replaying deferred scripts and schema validation, running script.teardown,
storing the summary - and the stream stays open, sending nothing, until that
pass ends. status is omitted only when the engine gave up waiting, 60s
after the last tick was sent (LIVE_SETTLE_TIMEOUT_MS), or the status write
itself failed. A client must read that as "ask the report", never as success:
the field is absent on that frame, not null, and a client older than it saw
no status at all.
elapsedSeconds is the time since load started, the instant the report's
testDuration is measured from: after the request is built and any
script.setup has run, immediately before the first submission (issue #2395).
Until then the run is still setting up, and every frame carries
elapsedSeconds: 0 with sendRate and throughput at 0, because both divide
by it. The last frame, published just after load ends, therefore reads within
a fraction of a second of the report's testDuration. currentRps and
currentSendRate do not divide by it: they divide by the trailing window's own
span on the monotonic clock (issue #2393), so they read 0 while nothing is
sent, and a window that reaches back before load start counts that idle time in
its span. An engine older than that issue
counted from when the run was registered, so a slow setup ran its live clock
ahead of the report and dragged the rates down. The last frame's sendRate is
still not the report's: the report divides requests sent by the sending
window, which ends before the end-of-run drain, where a live frame divides by
everything elapsed so far (GET /runs/:runId/report,
issue #2392).
A capacity run's frames carry one more key, the search's state (the
capacity row of the field reference below), here three seconds into the
search's third measurement:
A scenario run streams step events instead of metrics ticks. One per
step execution, on the same ring and the same monotonic id: numbering, so
Last-Event-ID resume works identically and a client that reconnects mid-run
replays the steps it missed:
event: step
id: 3
data: {"iteration":1,"stepIndex":0,"name":"Log in","outcome":"passed",
"statusCode":200,"latencyMs":42.7,"dataRowIndex":1,
"requestId":"req_abc123",
"tests":{"passed":2,"failed":0},"extractorMisses":1,
"unresolvedTokens":1,
"validation":{"checked":true,"valid":true,"matchedStatus":"200",
"matchedContentType":"application/json",
"failures":[],"failuresTotal":0}}
event: complete
data: {"event":"complete","runId":"run_1234567890","status":"completed"}
status carries the same three values and the same absent-means-ask rule as on
the metrics stream above.
outcome is one of passed, failed, skipped, errored, stopped - see
Scenario runs. dataRowIndex is present only for a run with
data, on the same terms as on the stored row, so a step reads the same live
and after a reload. stepsNotRun follows the same rule: present only on the
step whose error ended its iteration short of the plan's end, with how many
plan positions that cost (see Outcomes under Scenario runs),
and absent rather than 0 everywhere else. extractorMisses is the stored
row's count of extractions that found nothing (#3053), on the same terms, and
unresolvedTokens its count of names the step sent unresolved (#3248).
validation is the step's schema verdict (issue #681) in
the same shape and on the same terms - absent for a step of an unbound
collection and for one that sent nothing, and byte-identical to the node its
stored trace carries, so a watched run and a read-back one agree. tests is how
many of the step's assertions held (issue #724) - two numbers, because the ring
is fixed-size and a script may make hundreds of them; the list itself rides the
stored scripts node. It counts exactly the assertions that node lists -
both script phases, every level's (#2522), and assert.* elements beside
them - and is absent for a step that asserted none: 0 passed
would read as a result. requestId names the stored request the step ran
(issue #831) - the same id stamp_step_identity writes onto the stored trace,
so a step read live and the same step read back from the report name one
request, and a client watching a run can offer the way back to it before the
rows are written. One id is constant-size, which is why it rides the frame where
the assertion list does not; absent when the plan step names no stored request,
because an empty id is not a request. A stopped step carries no tests and
no validation: what its scripts made of a cancelled send is no verdict. A scenario
run publishes no metrics ticks:
its work is sequential, so per-tick aggregates would be a rate of one request at
a time rather than anything about the sequence.
Its stream opens with one plan frame (issue #1398), published before the
first step:
stepsPerIteration is the plan's length, steps in one pass over it.
iterations is how many passes the engine resolved - a data set's row count
where the run named no explicit count of its own. stepsExpected is
stepsPerIteration * iterations, an upper bound rather than a promise, on the
same terms as a scenario load run's requestsExpected while it runs (the live
frame table below): an errored step can end its iteration (see Outcomes under Scenario runs),
POST /runs/:id/stop ends the run, setNextRequest can walk
an iteration in fewer steps than the plan holds, and the
maxStepsPerIteration cap can end one that walks in more. It rides the same
monotonic id space as the step frames that follow - the same ring, so
Last-Event-ID resume works identically - and a client that attaches after
the frame has aged out of the retained ring simply never sees it: it should
read that as no total rather than compute a fraction of a number nobody sent,
and show an indeterminate bar the way it would against an older engine that
never sent this frame at all. One frame ahead of the work rather than a number
on every tick, because this run publishes no ticks to carry one: the load
path's total rides its metrics events precisely because that path has them.
(A collection run's report likewise reads its latency from the stored summary, not from
ticks: see the report.)
A run with a monitor block also streams
monitor events, one per successful scrape, interleaved with its metrics
ticks on the same ring and the same monotonic id: numbering - so
Last-Event-ID resume replays both kinds in the order they happened:
event: monitor
id: 12
data: {"timestamp":1234567890,
"series":{"node_cpu_seconds_total":3.75,"process_resident_memory_bytes":1048576}}
The payload is byte-identical to one data[] entry of
GET /runs/:runId/monitor, so the live overlay and the
history overlay are drawn from the same rows. A scrape that read nothing emits
no frame.
Field reference (every key of a metrics frame; MetricsCollector::get_current_stats() builds all but the trailing-window keys (eventsPerSecond among them) and a capacity run's capacity, which the metrics thread adds on every tick, and the second*, cumulativeLatency, cumulativePhases, streamTimeToFirstEvent, statusSeconds and scenario keys, which it adds on a gate tick):
| Field | Meaning |
|---|---|
totalRequests / totalSuccess / totalErrors |
Completed counts; totalErrors by the one error definition |
httpErrors / noResponse |
totalErrors split: an error status came back, or no response did |
cancelled |
Requests a Stop cancelled before they answered; in none of the counts above (issue #2136) |
errorRate |
totalErrors as a percentage of the status-code distribution's total |
currentRps / currentSendRate |
Completions / dispatches per second over the trailing window (issue #2393): at least the last second (LIVE_RATE_WINDOW_MS), divided by its actual span, and everything since the first frame until the stream has a second of frames. 0 for a window with nothing in it. A gate frame's pair is its stored row's current_rps / current_send_rate |
sendRate |
Requests dispatched per second, cumulative: requestsSent over the time since load start |
throughput |
Responses received per second, cumulative: totalRequests over the time since load start |
activeConnections |
Transfers active in the curl workers at the sample, the stored tick's current_concurrency. Instantaneous: a virtual user in a timer wait holds none, so a run whose users wait in step reads 0 or the user count depending on where the sample lands. windowAvgInFlight is the mean |
backpressure |
In flight at the sample: requests sent but not yet settled (RunContext::in_flight), plus, on a closed-loop single-request run only, every slot a timer.think wait still holds. A scenario run's timer waits are not counted, because its dispatcher treats a waiting virtual user as not in flight, and a constant_rps run reserves none, because it skips the timer (#3541). The same figure as the stored tick's backpressure and the high-water mark behind the report's peakConcurrency, so on a single-request think-timer run it exceeds requestsSent - totalRequests, and once a Stop has cancelled requests it is requestsSent - totalRequests - cancelled |
phase |
Where the run's worker is at the sample (issue #3568), on every frame: setup, sending, draining (the strategy returned on its own and backpressure is the in-flight requests the natural-end drain waits out, no longer new load), summarising or settled. A run moves forward only and may skip one; see Stop semantics for what a Stop does in each. Live only: no stored row carries it, and an older engine sends no such key |
droppedRequests |
Requests discarded at the maxInFlight cap (never sent) |
skippedRequests / stalledMs |
constant_rps only (#2911): requests a stalled pacer owed beyond its 100 ms catch-up window and skipped (never sent, not in droppedRequests), and the schedule time they cover in ms, skippedRequests ÷ targetRps. 0 on every other mode |
avgLatencyMs |
Mean perceived latency over the same requests as the percentiles and the max (Latency population): answered requests plus those that failed after their transfer ran |
avgQueueWaitMs |
Mean time queued before the wire, inside the generator or in libcurl waiting for a connection slot (#2394), over the same requests as avgLatencyMs (Latency population) |
windowAvgLatencyMs / windowAvgQueueWaitMs |
The same two means over only the requests that completed in the trailing window currentRps covers (issue #2393), from the difference of the run's sums and counts across it; null when nothing completed in it. A gate frame's pair is its stored row's window_avg_latency_ms / window_avg_queue_wait_ms |
windowAvgInFlight |
Mean requests in flight over the same trailing window (issue #2821): the time requests spent in flight during the window divided by its span (issue #3567), so a request open across the window counts whether or not anything completed. A request is in flight from submission to completion, queue wait included, and a Stop's cancellation ends it; a timer wait between requests and a request refused or skipped before it reached the event loop are not. With no think time it equals the virtual user count, and it does not alias the way activeConnections does. 0 for a window with nothing in flight, never null. A gate frame's value is its stored row's window_avg_in_flight |
latencySamples |
How many completions the tick's window held, the population of the three below (issue #2386). 0 says the window had no completion, which no percentile can say |
latencyP50Ms / latencyP95Ms / latencyP99Ms |
Live windowed percentiles over the latency population - the last tick's window (100 ms at the default cadence) sampled from a phaser-based hdr_interval_recorder; null when latencySamples is 0, never a 0 ms reading (issue #2386; an engine before it wrote 0). The capacity search steers by these |
cumulativeP50Ms / cumulativeP95Ms / cumulativeP99Ms |
The same percentiles over every completion so far, the span avgLatencyMs covers, merged from every window sampled up to this tick; on every frame, null until something has completed. The final report's latency block is the same population read from the run's own histogram |
secondSamples, secondP50Ms / secondP95Ms / secondP99Ms |
Gate frames only (issue #2385): the frame of the tick that wrote a stored row, about once a second, carries that row's figures - every window since the previous gate merged, and how many completions they held. The final frame carries them too, for the partial second since the last gate, which is stored nowhere. The percentiles are null when secondSamples is 0. Absent from every other frame |
cumulativeLatency |
Gate frames only (issue #2782), the final frame included: the run-so-far latency distribution, {minMs, p50Ms, p75Ms, p90Ms, p95Ms, p99Ms, p999Ms, maxMs, count}, over the same completions as the cumulative*Ms keys. null until something has completed, never zeros. The final frame merges the last window after the drain, so its figures are the report's latency block. Absent from every other frame |
cumulativePhases |
Gate frames only (issue #2782): {dns, connect, tls, firstByte, download}, each {meanMs, p50Ms, p95Ms, p99Ms, maxMs, count}, from the same per-phase histograms as the report's timingBreakdown, which every successful completion feeds. null until a completion has recorded its phases; absent when the run has the phase histograms off, so absent means "not measured" and null means "nothing yet". Read while the run is still recording, one phase at a time, so a mid-run reading's phase counts can differ from each other and from its frame's counts by the completions that landed between the reads; the final frame is read after the drain and its means are the report's avg*Ms. Absent from every other frame |
streamEvents / streamsOpen |
Streaming runs only (issue #3236; a single-request run with stream, or a collection load run with a streaming step, #3304), on every frame, and only while stream_metrics is on: the events delivered so far, counted on the write path as they arrive rather than when a stream completes, so a run of long streams is not blank until the first one ends; and the streaming transfers open at the sample, which on a collection run that mixes streaming and ordinary steps is fewer than activeConnections (that one counts every transfer). A stream leaves streamsOpen however it ends (a cap, the server's close, an error, a Stop), so the settled frame reads 0. Once the run settles, the final frame's streamEvents equals the report's stream.totalEvents, the unterminated last frame a close completes included; a run a Stop ended also counts the events of the streams it cancelled, which the report does not. Absent from every other run's frames, never zeroed |
eventsPerSecond |
Streaming runs only (issue #3236), on the same frames as streamEvents: events per second over the trailing window currentRps covers, from the difference of streamEvents across it. 0 on the first frame and for a window with nothing in it. Live only: no stored row carries it |
streamTimeToFirstEvent |
Gate frames only (issue #3236), on the runs that carry streamEvents: {p50, p95, p99, max, count} in milliseconds, from submission to the first event, over the streams completed so far, from the histogram behind the report's stream.timeToFirstEvent; a stream still open is not in it. Absent until a completed stream delivered a timed event, and from every other frame |
bytesSent / bytesReceived |
Cumulative wire bytes: every hop's headers and body, each counted once, so a followed redirect counts its own response (body included) and, for a 307/308, the request body it sent again (issue #2893) |
requestsSent / requestsExpected |
Progress for bounded modes (drives ETA). A scenario iterations run starts requestsExpected at iterations x steps per iteration, an upper bound while it runs because an abandoned iteration never sends its later steps; a natural end settles it to the sent count, so the final frame reads 100%. A stopped run keeps the upper bound (issue #2914) |
capacity |
Capacity runs only (issue #2928), on every frame from tick 0: where the search stands, {level, levelElapsedMs, levelsJudged, stopReason?}. level is the concurrency being measured, 0 until the first level opens (tick 0 is emitted before it does). levelElapsedMs is the time since that level opened, 0 while level is 0, and held at the moment the search ended once it has. levelsJudged counts the levels judged so far, a re-measured level once per measurement, so the report's capacity.levels holds that many rows. stopReason appears once the search has ended, with the value the report's capacity.stopReason carries, stopped included, and is absent while it runs. The four are published together, so one frame never pairs a level with another level's time or count. Absent from every other run's frames, never zeroed |
status2xx–status5xx |
Per-class counts |
statusCodes |
Full per-code distribution map |
statusSeconds |
Gate frames only (issue #2866), the final frame included: the seconds since load start that closed since the previous gate, [{second, span, counts}] with span 1 and counts [2xx, 3xx, 4xx, 5xx, error], each response counted in the second it completed in. A gate frame's entries are its stored row's status_seconds, drained once for both, so live and History hold the same seconds; the final frame's are the seconds closed since the last gate, which only it carries. [] when no second closed. Absent from every other frame |
scenario |
Gate frames only (issue #2823), the final frame included, and only on a scenario load run: the sequence so far, {iterations, iterationsCompleted, iterationsAbandoned, stepsExecuted, steps: [{index, name, executed, errors}]}, one steps entry per plan step in plan order. The same counters as the stored summary's scenario block (iterations, iterations_completed, iterations_abandoned, steps_executed, and each step's executed and errors), read while the workers still write, so a mid-run reading's figures can differ from each other by the completions that landed between the reads; the final frame is read after the drain and equals the summary. No latency: a step's percentiles are in the report alone. Absent from every other frame and from every frame of any other run |
Read order within one tick. The metrics thread snapshots the status-code
distribution first, then get_current_stats() reads the completed count
(totalRequests) afterwards, and the stored row's requests_completed is read
after the same snapshot. So totalErrors, errorRate and the status* keys
all come from the earlier snapshot and totalRequests, totalSuccess and
throughput from the later read. A completion landing between the two makes
status2xx + status3xx up to one tick of completions lower than totalSuccess,
and a client's totalErrors / totalRequests marginally lower than the frame's
errorRate. The skew is invisible at the default 1 Hz cadence, and the order is
the safe one: errorRate divides by the snapshot's own total, so no rate
exceeds 100 percent.
Each metrics event carries an id: equal to its zero-based offset. The
browser's built-in EventSource retry automatically replays this id as
Last-Event-ID on its own intra-connection retries (no application code
needed), and the stream resumes from Last-Event-ID + 1.
?lastEventId=<id> is the same resume point as a query parameter, for a
client that reconnects by hand: EventSource sets Last-Event-ID only on its
own retry and exposes no way to set a header on a fresh connection. The
header wins when both are given. Frame ids start at 0, so lastEventId=0
means "I saw frame 0" rather than "from the start"; absence is what means the
start. A value that is not a non-negative frame id is refused with 400 and
code invalid_last_event_id rather than resumed from the start, which would
replay every retained tick to a client that already holds them - the
change feed and inbox streams'
rule.
Replay window. The in-memory tick topic is a bounded ring, so a long run's
memory does not grow with its duration. Its span is liveReplayWindowMs
(default 300000, i.e. 5 minutes) and the tick count is derived from that window
and the configured cadence - liveReplayWindowMs / liveTickIntervalMs, 3000
ticks at both defaults. The bound is a duration rather than a fixed count
because the cadence is itself configurable: one tick count would mean a
30-second window at liveTickIntervalMs=10 and a 50-minute one at 1000.
liveReplayWindowMs = 0 means the full run (no time limit). Whatever the pair,
the ring is capped at liveMaxRetainedTicks (default 50,000, ~50 MB), so a
fast cadence reaches that ceiling before a long window does. Raising it is
cheap at stock settings - the window, not the ceiling, is what sizes the ring.
Ids keep counting past an eviction, so they stay monotonic; a Last-Event-ID
older than the retained window resumes from the oldest retained tick rather than
replaying from 0, which means a client that was disconnected for longer than the
window sees a gap, not a duplicate flood.
The window also bounds the replay-from-0 path, which the bundled app takes
on a first attach: a dashboard attaching mid-run rebuilds its chart from the
retained ring. Its Reconnect resumes with ?lastEventId= instead and is sent
only the frames after the last one it holds. That is why liveReplayWindowMs is
the same setting as the app's live-chart window rather than a second one to
keep aligned - the app's Settings → Live Dashboard → Chart window picker
reads and writes this entry (GET/POST /config), so the span the engine
retains and the span the chart displays cannot disagree. Editing it here and
editing it there are the same action.
The final metrics event is emitted only once the run's worker has actually
settled. On POST /runs/:runId/stop the engine keeps ticking while in-flight
requests are cancelled and counted as cancelled, so the last live numbers
agree with the stored report rather than freezing at the moment of the stop
request.
Application-level reconnect: a client that closes the EventSource itself
(e.g. after observing readyState === CLOSED) and opens a new connection
resumes with ?lastEventId=<id of the last frame it held>, because a fresh
EventSource sends no Last-Event-ID and would otherwise start at offset 0
and replay the entire retained topic, duplicating ticks already shown. A
connection that names no resume point is the first attach and does start at 0.
The other recovery is to converge on the stored report via
GET /runs/:runId/report (the same path used at normal run end).
Responses:
- 200 - SSE stream (active run, or finished run still within the retention window).
- 404 - no live topic for the run. The flat body is {"error", "code",
"hint"} and code says which of two cases it is (#2775):
- live_expired - the run is stored but its topic aged out past
liveRetentionMs; error is Live metrics for this run are no longer
retained.
- run_not_found - the engine has no run by that id; error is Run not
found or expired.
Both hint Use /runs/:runId/report for the stored report, and a client
should fall back to the stored report in either case (for run_not_found the
report then answers its own 404). code is for clients to branch on; the
bundled app has no reader for it yet. MCP's get_live_metrics reads it
(#2779): live_expired answers that the buffer expired and the run still
exists, naming get_run_report, and run_not_found keeps the unknown-id
text.
Tuning: liveTickIntervalMs (live tick cadence, 10–1000ms),
liveReplayWindowMs (retained replay span and the dashboard's chart window,
0–3600000ms; 0 = full run), liveMaxRetainedTicks (the tick ceiling for that
window on both sides, 1000–500000) and liveRetentionMs
(post-completion retention, 0–600000ms; 0 disables retention) are configurable
via POST /config.
GET /runs/:runId/events¶
Relay a streaming run's events via Server-Sent Events (issue #573). Started by
POST /execute with "stream": true, which returns this URL as eventsUrl.
The endpoint replays the run's retained events, then tails until the stream
terminates, and closes with a complete event naming the termination reason.
complete is sent only once the post-request script has run and the run row
and trace are stored (#3239), so a GET /runs/:runId/report made on it already
reads the result and a terminal status.
Like the live-metrics topic, the ring is retained for liveRetentionMs after
the stream ends, so a client that connects late - even after a short stream has
already finished - still receives the whole series.
Events:
event: open
id: 0
data: {"statusCode":200,"statusText":"OK","headers":{"content-type":"text/event-stream"}}
event: message
id: 1
data: {"event":"token","data":"Hello","sourceId":"42","receivedAt":1234567890}
event: complete
data: {"runId":"run_1234567890","reason":"completed","totalEvents":128}
openis published once, as soon as the response's header block arrives, so even a late consumer learns what the stream connected to. A reply with no body (a204, a bodiless401, an empty200) still publishes it, with its status, beforecomplete(#3342). WithfollowRedirectson it describes the hop the stream ends at: a redirect the stream follows publishes noopen, and its body is neither an event nor counted. Neither does an interim1xx(a100 Continue) nor a proxy's answer toCONNECT: a tunnel refused there ends the stream aserrorwith noopen. A stream that failed before any response arrived has none either, and neither does one that ends on a redirect the engine refuses to follow (too many hops, an unsendable scheme).messagecarries one upstream event: itseventname (messagewhen the origin sent none), itsdata(multipledata:lines joined with\n), the origin's ownid:assourceId, andreceivedAt. An event larger thansseMaxEventBytesis stored as a prefix and says so in band, withdataTruncated: trueanddataBytes(the size as sent) - never silently cut.complete'sreasonis one ofcompleted,stopped,shutdown,maxStreamEvents,maxStreamDurationMs,idleTimeout,error; see POST /execute. No frame carries the exchange'swarnings(issue #3315): they are on the stored trace, which the report already holds whencompletearrives.
sourceId is not the resume point. id: on the wire is this relay's own
frame offset, which is what ?lastEventId= / Last-Event-ID takes; sourceId
is what the origin would want back. Conflating them would make one of the two
resumes silently wrong.
Resume picks up at the frame after the one named, so a dropped consumer
re-renders nothing. The header wins over the query parameter when both are
present (EventSource cannot set a header on a fresh connection, so a client
owning its retry uses the parameter). Unlike the inbox's capture ids, frame ids
start at 0, so lastEventId=0 means "I saw frame 0" rather than "from the
start"; absence is what means the start. A present-but-unreadable value is a
400 (invalid_last_event_id) rather than a silent replay from 0. A resume
point older than the retained window is fast-forwarded to the oldest retained
frame rather than looping on ids that will never come back.
One consumer at a time. Each stream parks a cpp-httplib pool thread for its
whole life, so a second concurrent watcher is a 409
(run_events_in_use) - but a claim whose holder has stopped writing for two
keep-alive intervals is taken over instead of refused, since EventSource
treats a 409 as fatal and a reconnect racing the previous socket's death would
otherwise kill the stream for good.
Responses:
- 200 - SSE stream (live stream, or finished one still within the retention
window).
- 400 - unreadable lastEventId / Last-Event-ID.
- 409 - already being streamed.
- 404 - no stream for this run, or it expired past liveRetentionMs; the body
hints GET /runs/:runId/report, whose trace carries the stored events node.
Runs¶
GET /runs¶
List test runs (design mode, load tests and collection runs), newest first
(start_time DESC, id DESC - the only order the UI uses; the id tiebreak
makes the order total, so runs sharing a millisecond page in a fixed order and
a page boundary inside such a tie neither repeats nor skips a row). Rows carry
a compact summary rather than the full configSnapshot, so the polled history sidebar
stays cheap as history grows.
Each row's summary is derived from that run's config_snapshot, and the
derivation is cached per run id (issue #1150): a snapshot is written once,
when the run is created, so a repeated poll re-serves what the previous one
built instead of re-parsing one snapshot per row every tick - 50 at the default
page size, up to 500 at the cap. The cache is bounded and
holds nothing a request cannot rebuild, so it changes no answer - a run deleted
between polls is gone from the list because the query no longer returns it, not
because anything was invalidated. This route also logs at debug, not info: it
is the one endpoint a visible client polls, and an info line here reached the
console of every engine started at the default app verbosity, every five
seconds.
Query parameters (every one optional; the answer is always the paginated envelope):
- limit - page size (default 50, invalid/≤0 falls back to 50, capped at 500).
- offset - rows to skip (default 0, negative floored to 0).
- before - a keyset cursor, <startTime>:<id>: the page starts after that
row (#2978). Pass the previous page's pagination.nextBefore unchanged; the
value is split on its first :, so an id holding one is read whole. Where
offset makes SQLite step over every row before the page, a cursor page
seeks idx_runs_start_time to the row and reads about limit rows however
deep it is, and it does not shift when a new run starts between two pages.
Every filter below still applies, and total still counts the whole filter,
not the rows after the cursor. A value that is not an integer, a : and a
non-empty id is a 400 with code invalid_before; before beside a
non-zero offset is a 400 with code before_with_offset (an offset of
0 is the same as none). offset stays for a client that jumps to a page
number.
- type - design | load | scenario (an unrecognised value is ignored, not an error).
- status - a RunStatus string (pending | running | completed | failed | stopped; unrecognised ignored).
- requestId - exact match on the run's linked request.
- collectionId - exact match on a run's stored scenario.collectionId, read
out of the snapshot as JSON. This is the deliberate opposite of q below: it
matches the field, never the text around it, so a design run whose URL
happens to contain the id does not come back. A collection run records the
path, and so does a load run driven over a collection (#3544); a
single-request design or load run never does, so it can never match. Add
type=load to leave the collection's sequential runs out. An id nothing has
run is an empty page, not an error. A collection's most recent run is
?collectionId=<id>&limit=1, since the list is already start_time DESC.
- q - case-insensitive substring over the stored config_snapshot text
(SQL LIKE). It searches the raw snapshot, so it may over-match JSON keys or
structure - acceptable for a search box.
- baseline - true lists only runs pinned as baselines, false only unpinned
ones (any other value is ignored, like an unrecognised type). Leaving it out
lists both, so omit it rather than passing false to mean "either". A
request's current baseline is ?baseline=true&requestId=<id>&limit=1, and a
collection's ?baseline=true&type=load&collectionId=<id>&limit=1, since the
list is already start_time DESC - the lookups both the history view's
vs-baseline strip and the MCP compare_runs tool make.
- origin - app | mcp | other, exact match on the run's stored
origin.kind (#1817; see POST /execute). Like an
unrecognised type, any other value is ignored rather than refused, so a
client on a newer vocabulary than the engine gets a wider list, never an
error. A run recorded before the field existed matches other. There is no
client filter: narrowing to one MCP client is done client-side over the
rows this returns.
Every parameter composes with every other; each one left out is a wildcard.
summary carries exactly these seventeen snapshot keys: url, method,
mode, duration, concurrency, iterations, targetRps,
startConcurrency, rampUpDuration, comment, followRedirects,
maxRedirects, requestName, dataFileName, dataFileHash,
dataFileCastNumbers, and httpVersion.
The first sixteen are each omitted when absent from the snapshot (a
malformed snapshot yields an empty summary, never a 500); httpVersion
alone is always present. iterations and targetRps (issue #2437) are what
the run was sent, never a default the engine filled in: an iterations run's
request count, and a paced run's rate. targetRps is the one rename - the
POST /runs body may name the rate rps or targetRps, the row reports it
as targetRps (the rate the engine paced at: rps, or targetRps when rps
is absent, null or zero), and the report's configuration does the same. A field the run was not sent has no key
here even though the engine ran its default (see
POST /runs); a client that wants a default
visible sends it. startConcurrency and rampUpDuration (issue #1935)
are the ramp-up knobs, so only a ramp_up run has them, e.g.
"startConcurrency": 2, "rampUpDuration": "10s" beside "concurrency": 50;
they are the same two keys the report's configuration carries. requestName
is the request's name as the client sent it when the run started -
never re-read from the requests table, the same trust model url and
method already have here - so a request renamed or deleted since does not
change what a past run's row says it invoked, and a run whose client omitted
the field (or one recorded before it existed) has no key at all rather than a
fabricated name. It reaches config_snapshot the same way url/method do:
whatever the client's POST /runs or POST /execute body carried; the
renderer sends it from execIdentity (execute-mapping.ts), the same field
POST /compose's requestId path already stamps for the
script sandbox's pm.info.requestName. dataFileName and dataFileHash
(issue #2051) name the file a single-request run's data rows came from, by
display name and SHA-256 of its bytes (64 lowercase hex), never its path; a run
sent without a file name has neither. dataFileCastNumbers (issue #2540) is
true when that file's numbers were read as numbers, and absent otherwise.
Every run since issue #1488 adds an eighteenth, acceptEncoding: true when the run negotiated a compressed response
(negotiateCompression for a collection run, loadNegotiateCompression for a
load run - see Default request headers), false
when it did not, and omitted, not defaulted, for a run recorded before
that issue -
the baseline comparison (below) is the one reader that treats an absent key as
false, matching what every such run actually sent. A raw POST /runs body of
"httpVersion": null (erased before execution, so it behaves exactly like an
absent key - see POST /runs) lands in the stored snapshot
verbatim, and a run predating this field has no key at all; neither case
recorded a protocol, so both normalize to the literal string "auto" rather
than being omitted, which would misrepresent "nothing was recorded" as "we
lost it". Do not read "auto" on an old run as the protocol it used: a load
run stored before 0.11.0 hardcoded CURL_HTTP_VERSION_2TLS, and every run
before it went out as HTTP/1.1 regardless, because nghttp2 was not linked. The full snapshot stays available on
GET /runs/:runId. That route does not build a summary row at all: it returns
the full configSnapshot, which already holds every key above. The same seventeen
keys are on the row PUT /runs/:runId/baseline answers
with, since both are built by one function; that row carries no
resultSummary.
A collection run (type: "scenario") carries none of the single-request
keys above (url through dataFileCastNumbers): its work is a sequence, so there is no
single url, method or mode to report. Its row instead carries a
nineteenth key, scenario, present on scenario runs only:
"scenario": {
"collectionId": "col_1234567890",
"iterations": 3,
"recursive": true,
"stepCount": 12,
"dataFileName": "users.csv",
"dataFileHash": "<sha256>",
"dataFileCastNumbers": true
}
stepCount is the length of the snapshot's step manifest, not the manifest
itself - a row that shipped every step's name, method and URL would undo the
reason summary exists. The manifest stays on GET /runs/:runId. Each of the
seven keys is omitted when the stored snapshot has no such key: dataFileName and
dataFileHash (issue #2051) are the data file a run's scenario.data came
from, so a run sent without one has neither, and dataFileCastNumbers (issue
2540) is present, as true, only when that file's numbers were read as numbers.¶
hasWarnings (issue #1527) is summary's twentieth key, true on a run
whose stored summary.warnings array (issue #1503) is non-empty and
omitted otherwise - a run still in progress, one whose terminal write
failed, or one that finished with nothing to say. Unlike the other keys
above, it is not read out of config_snapshot and not part of the cached
compact summary: it is a completion-time fact, read fresh off the row on
every poll, so a history surface that polled a still-running run sees the
glyph appear on the next poll after it finishes, never stuck at the answer
its first poll cached. The full warnings array itself stays on
GET /runs/:runId's summary.
baseline is on every row, true only for a run pinned through
PUT /runs/:runId/baseline. It is also on
GET /runs/:runId, so a client that opened a run directly can draw the pin
without listing.
origin is on every row and on GET /runs/:runId: {"kind", "client"},
who started the run as the starting client asserted it (#1817; the rules are on
POST /execute). client is the MCP client's name for an mcp
run and null otherwise, and on an mcp run whose client sent no name. A run
recorded before the field existed reads {"kind": "other", "client": null}.
Metadata, not identity: nothing authorises on it.
resultSummary is what a design run's row says about the exchange:
statusCode and latencyMs, and nothing else. A design run is one request and
one response, so its outcome fits on the row and a page of them costs one extra
query. The two numbers rather than the whole result
GET /runs/:runId attaches: it carries the exchange's trace,
request and response bodies included, which is a per-row cost a list cannot
take. A design run with no stored result - still running, or one whose result
write failed - omits the key rather than reporting statusCode: 0, which is
the wire's own way of saying the request never reached a server.
A load run's row carries its own resultSummary once the run is terminal
(completed, failed or stopped; #2130), read from the whole-run summary the
run stored, never from its result rows, which are many and unbounded:
| Key | Meaning |
|---|---|
rps |
Achieved requests per second over the run, the report's summary.avgRps |
p95Ms |
95th-percentile latency in milliseconds, the report's latency.p95; omitted when the run timed no request (latency.count 0), not a stored 0 |
errorRate |
Percentage (0-100) of the run's status-code distribution that was errors: a status outside 2xx/3xx, or no response at all |
verdict |
"passed" or "failed": the run's verdict against its declared thresholds, the same one the report's thresholdValidation.verdict prints |
assertions |
The run's assertion block (#3537), the report's top-level assertions as it serves it, for both load run kinds: exact and sampled (each {passed, failed}), errored and teardownFailed. Beside errorRate, not folded into it |
assertionsPassed, assertionsFailed |
assertions.exact plus assertions.sampled, for readers older than the block (#2820, #3458). A required extract.* miss is in assertionsFailed, the count a maxAssertionFailureRatePct check's assertionsExact reports. errored and teardownFailed are not in it |
capacity |
A capacity run's headline (#2930), the same three keys of the report's capacity section: stopReason, and maxHealthyConcurrency / kneeConcurrency each only when the search found that level |
drainCut |
{cancelled}, the requests a Stop cut from the run's own drain (#3538), the report's summary.drainCut. Present only on such a run, which a reader treats as not judged unless verdict is "failed"; verdict itself stays the budgets' own |
Each key is omitted when the stored summary does not record it, never
zeroed: errorRate is absent when the run recorded no status codes, and
verdict is absent when the run declared no budgets - it was never judged,
which is not the same claim as passing. The three assertion keys are absent
together, for a run that made no assertion and errored nowhere. A run stored
before #3537 reads as it did: a scenario load run's assertions is its
scenario.assertions as exact alone, absent on a run stored before #2820,
and a single-request run's is its assert.* and script.* rows of elements
as exact (counted per execution, a required extract.* miss not in it) and
its testValidation as sampled; neither has errored or teardownFailed.
A scenario load run whose every deferred pm.test failed against 200s
reads "resultSummary": { "rps": 172.0, "p95Ms": 12.4, "errorRate": 0,
"assertions": { "exact": { "passed": 0, "failed": 0 }, "sampled": { "passed": 0,
"failed": 91 }, "errored": 0, "teardownFailed": 0 }, "assertionsPassed": 0,
"assertionsFailed": 91 }. capacity is absent on
every run that was not a capacity search; inside it, maxHealthyConcurrency
is absent when the very first level already breached the budget and
kneeConcurrency when the search ended without the target giving out, the
report's rules for the same keys. A capacity search that stopped on its
latency budget reads "capacity": { "stopReason": "slo_exceeded",
"maxHealthyConcurrency": 48, "kneeConcurrency": 64 }. A run whose drain a
Stop cut with 15 requests unanswered reads "verdict": "passed", "drainCut":
{ "cancelled": 15 } when the answered requests met every budget. A pending or running load row, and
a terminal one with no stored summary (the engine stopped before writing it),
carries no resultSummary at all.
verdict is the verdict as stored, even for a stopped run, whose partial
data the app shows as "Not judged" rather than passed or failed. errorRate
uses the same failure definition as the report's summary.errorRate, over the
stored status-code distribution, and is omitted when no distribution is stored.
A collection run's row (type: "scenario") carries one once it is terminal
too (#2954), read from the scenario block of the stored summary under the
same rule: nothing for a pending or running row, nothing for a terminal row
whose summary is not stored yet. The five counts are the step
outcomes, which are disjoint:
| Key | Meaning |
|---|---|
passed, failed, skipped, errored, stopped |
How many steps ended each way, the report's scenario.passed / failed / skipped / errored / stopped. errored is a step whose script threw or whose exchange did not complete, kept apart from failed so a run whose steps only errored does not read clean; stopped is a step a Stop or a shutdown cut short (#3397), absent for a run stored before it |
verdict |
As on a load row: the run's verdict against its declared thresholds, absent when it declared none, and as stored even for a stopped run |
Each key is omitted when the stored summary does not record it, never zeroed,
and a stored summary with no scenario object (a run stored before collection
runs wrote one) adds no resultSummary. A clean four-step run reads
"resultSummary": { "passed": 4, "failed": 0, "skipped": 0, "errored": 0, "stopped": 0 }:
the zeros are recorded counts. The load figures (rps, p95Ms, errorRate)
are not on this row; the report has them.
endTime is null while a row's status is pending or running and the
stored value once it is completed, failed or stopped (#2953). The database
seeds the column with startTime when a run is created, which would read as a
run that took no time, and clears it to 0 once a load or collection run is
running (#3340); a client takes "still going" from the null, and the same
rule holds for GET /runs/:runId, the report's metadata.endTime and the
PUT /runs/:runId/baseline row.
Response (envelope):
{
"data": [
{
"id": "run_1234567890",
"requestId": "req_1234567890",
"environmentId": null,
"type": "load",
"status": "completed",
"startTime": 1234567890,
"endTime": 1234567891,
"baseline": true,
"origin": { "kind": "app", "client": null },
"summary": {
"url": "https://api.example.com/users",
"method": "GET",
"mode": "constant_rps",
"duration": "60s",
"concurrency": 100,
"comment": "nightly",
"followRedirects": true,
"maxRedirects": 10,
"httpVersion": "auto"
},
"resultSummary": { "rps": 98.7, "p95Ms": 41.3, "errorRate": 0.4, "verdict": "passed" }
},
{
"id": "run_1234567891",
"requestId": "req_1234567890",
"environmentId": null,
"type": "design",
"status": "completed",
"startTime": 1234567892,
"endTime": 1234567893,
"baseline": false,
"origin": { "kind": "mcp", "client": "claude-code" },
"summary": { "url": "https://api.example.com/users", "method": "GET", "httpVersion": "auto" },
"resultSummary": { "statusCode": 200, "latencyMs": 34.2 }
}
],
"pagination": {
"total": 812,
"limit": 50,
"offset": 0,
"hasMore": true,
"returned": 50,
"nextBefore": "1234560001:run_1234560001"
}
}
hasMore is read off the rows: the engine fetches one row past limit, so it
holds on a cursor page, which has no offset to add to total. nextBefore is
the cursor naming this page's last row whenever hasMore is true (an offset
page included, so a client can switch to cursors after its first page) and
null on the last page. A cursor page echoes offset: 0.
GET /runs/:runId¶
Get details for a specific run.
Response: The run object shown in GET /runs (id, requestId,
environmentId, type, status, configSnapshot, startTime, endTime,
baseline, origin). endTime is null until the run's status is
completed, failed or stopped, as on the list row.
While the engine holds the run active, the object also carries phase, where
its worker is: setup, sending, draining, summarising or settled
(issue #3568), the same value as the live frame's
phase. draining means the run's own end has come and
it is waiting out the requests still in flight, which a Stop
cuts short without changing the outcome. The phase is
never stored, so a run no longer active (finished, or the engine restarted) has
no phase key at all; read status there.
For a design run that has at least one stored result, the response also
carries a result object with that run's single exchange - the only other
place it appears is GET /runs/:runId/report, whose results array and
metadata.configuration are load-test concepts and are absent for a design
run. result is design-only by construction: it serves the first stored row
on the assumption that there is exactly one, and a scenario run has one per
step - its steps are read from the report's results array instead.
{
"id": "run_1234567890",
"requestId": "req_1234567890",
"environmentId": null,
"type": "design",
"status": "completed",
"configSnapshot": { "...": "the run payload as composed, credentials withheld" },
"startTime": 1234567890,
"endTime": 1234567891,
"baseline": false,
"origin": { "kind": "app", "client": null },
"result": {
"timestamp": 1234567891,
"statusCode": 200,
"statusText": "OK",
"latencyMs": 42.1,
"error": "optional, only when the request failed",
"trace": { "request": { "...": "..." }, "response": { "...": "..." } }
}
}
trace.error_type / trace.error_message are present when the exchange
failed, and trace.response when it did not or when the failure came after a
header block arrived (issue #3423): an undecodable body, a timeout mid-body,
too many redirects. Such a failure is still reported at statusCode 0, and
its trace keeps the headers, headerLines, httpVersion and body the live
answer showed beside the error, so a client must not read the presence of
response as success. A failure that received no header block (a refused
connection, an unresolved host, a failed handshake) has no trace.response.
A proxy's answer counts as a header block: a proxy's refusal, or headers on
the tunnel it opened, are kept as the live answer shows them.
Every trace.response carries bodyBytes (issue #3423), the body's length in
bytes, which a client cannot recount from body because a JSON string's
length is not its UTF-8 size. It is the length the engine held, which for a
bodyCapped response is the prefix the read cap kept; a streaming run's is
the body bytes the server delivered (issue #3238), which its body can be
shorter than (an event stream stores none, any other reply at most
maxDesignResponseBodyBytes; see POST /execute). A row
stored before #3423 carries it only on a cut or streamed response.
If the engine truncated a body for storage (over maxTraceBodyBytes), the
affected trace.request and/or trace.response object carries
"bodyTruncated": true, and trace.request gains "bodyBytes": <original
length>; a storage cut keeps the response's bodyBytes rather than
restating it. Absent when the body fit. A text body then holds the first
maxTraceBodyBytes bytes of the original, less an incomplete last UTF-8
character the cut would leave, so it can be up to three bytes shorter and
never ends in a U+FFFD the server did not send. Clients surface this as a
"body truncated for storage" notice and re-send to fetch the whole body. A
trace.response with "bodyEncoding": "base64" (see
POST /execute) is measured in decoded bytes: its body is
the base64 of the first maxTraceBodyBytes bytes rounded down to a multiple
of three, so the slice still decodes, and bodyBytes counts decoded bytes.
configSnapshot.body is capped the same way, independently of the trace
(issue #1486): content over maxTraceBodyBytes is cut to that length and the
body object gains the same bodyTruncated / bodyBytes pair. A run can be
truncated on one side and not the other, since each is written by its own call
into sanitize_config_snapshot.
configSnapshot withholds the composed request's credentials (issue #1803):
auth is reduced to {"mode": ...}, a header named in the shared secret set
(Authorization, Cookie, X-Api-Key, ...) or by the request's apikey auth
keeps its name with the value "<redacted>", and every value of a variable
marked secret in the payload's scopes (globals, environmentId, the collection
chain of requestId's request, else of the composed collectionId, issue
3461; for a scenario run, the chain of the run¶
collection and of every folder a step sits in, so a recursive run masks a
secret held on a sub-folder, issue #3270) is written as <redacted> wherever
it landed in url, params, headers or body, in its raw, percent-encoded
(strictly, and as composition writes a query value, a path, a fragment and
user info, which leave / @ & : + ' raw where the strict form escapes them),
JSON-escaped and XML-escaped forms (a JSON body holds pa"ss as pa\"ss). A
value under four characters is not masked. result.trace is the record of
what was sent and keeps it all. A run stored before this change returns its
snapshot as it was written.
A load or collection run's configSnapshot also carries defaultHeaders
(issue #1488), the run's resolved decision at start about what the engine
would add to a request nobody wrote it into - never re-read for the send
itself (see Default request headers), kept only
so a later run's report can say whether the two measured under the same
conditions:
"defaultHeaders": { "userAgent": "Vayu/0.26.0", "requestId": false, "acceptEncoding": true, "expectContinue": false }
expectContinue (issue #2516) is whether sendExpectContinue let libcurl add
Expect: 100-continue to a body over 1 MiB, which makes it wait up to a second
for the server's answer before sending. A run recorded before it has no such
key, and a comparison reads that as false, which is what the run sent.
Absent on a design run (it carries no throughput to compare) and on any run recorded before this issue.
POST /runs/:runId/stop¶
Stop a running load test or collection run. The engine signals the run, waits up to 5s for its worker to settle, and answers with a summary of what the run actually did. A collection run's summary is optional; see Stopping a collection run below.
What a Stop means depends on the phase it lands in (issue #3341). A load
run moves through setup, sending, draining, summarising and settled,
and the first Stop is latched with the phase it arrived in. The phase is never
stored; while the run is active it is published as phase on every live
metrics frame and on GET /runs/:runId
(issue #3568).
- A Stop before the strategy returns (
setuporsending) decides the outcome, and the run endsstopped. The queued backlog is thrown away rather than sent, and transfers already in flight are cancelled (removed from curl and completed as aCANCELLED"Request cancelled"), so the target stops receiving traffic immediately and the stop's latency does not belong to the upstream. A cancelled request was submitted, so it is counted, but not as an error (issue #2136): it issummary.cancelled, outsidetotalRequests,errorsanderrorRate(see What counts as an error). Every request the run sent is in exactly one oftotalRequestsandcancelled. - A Stop after the strategy returned on its own (
draining) decides nothing about the run's end. A run that ends naturally lets its in-flight requests finish, but only up to its effective timeout (its owntimeout, else thedefaultTimeoutsetting) plus a 2s grace, except a streaming run, whose bound is itsmaxStreamDurationMsplus grace (the 5s stream backstop plus the same 2s, issue #2834). A Stop in that drain cuts it short at once: the transfers still in flight are cancelled and counted ascancelled, not as errors, because the operator asked for it. The run keeps its own end -completed, orfailedwhenthresholds.failRunjudges it so - and its sending window is what it would have been without the Stop, since the Stop ended no sending. When the Stop cancelled anything, the summary records it asdrainCut: {cancelled}(issue #3538), and the run reads not judged ("15 requests were still unanswered when the drain was stopped") unless a budget it already missed fails it: the requests the Stop cut are the slowest the run sent, and judging what is left would pass a run on its fastest answers. A Stop in either phase also ends the deferred test replay and any script still running (#3460): the running script stops at its next interrupt poll and no further sample is replayed, sotestValidation.samplesTestedcounts the samples the replay reached and the worker settles within the 5s below instead of after each remaining sample'sscriptTimeout.script.teardownstill runs after a Stop latched before it (see scripting.md, "A Stop ends the script itself"). - A drain that hits its deadline with no Stop cancels what is still
outstanding the same way, and because nobody asked for that one to stop, it
is an error with no response, not a cancellation. Without that bound an
upstream that never answers would hold the run in
runningindefinitely.
POST /shutdown follows the same rules: it also cuts a
natural-end drain short and leaves the run completed.
Response (active run). status is the stored status once the worker has
written a terminal one; before that it is stopped when the Stop decided the
outcome, and running when it landed after the run's own end (the draining
phase), where the worker has not yet written the completed or failed it will
end with. running there is accurate rather than a failure to stop: the drain
is already cancelled, and the terminal status follows once the worker writes
it. When the worker has not settled within the 5s, the answer also carries
message: "Stop signalled; the run had not settled within the 5s grace
period; read the report" (#3342); a run that settled carries none.
{
"status": "stopped",
"runId": "run_1234567890",
"summary": {
"totalRequests": 1500,
"errors": 5,
"httpErrors": 3,
"noResponse": 2,
"cancelled": 12,
"errorRate": 0.33,
"avgLatencyMs": 38.9
}
}
errors and errorRate are the one error definition,
the same figures the live tick and the report show; httpErrors and
noResponse split errors. cancelled is the requests this stop cancelled,
counted in none of them.
avgLatencyMs is the same average the final report and the live ticks show:
the latency sum over the latency population, divided by
the number of requests in it. It is not divided by totalRequests (which counts
requests that carry no latency, so it would report a lower figure here than
everywhere else for the same run) nor by the success count (a timeout's
duration is in the sum).
A run that is already finished answers {"status": "<status>", "runId": ...,
"message": "Run already <status>"}; one that is not in memory answers
{"status": "stopped", "runId": ..., "message": "Run was not active"}. That is
a buffered design send, or a run still pending before its worker started
(#3340): the row moves to stopped from pending or running only, so the stop
stands. A worker that had not started yet finds the row stopped and ends
without sending; one that started in the meantime is signalled too. A buffered
send's exchange still completes and its result is stored, under a row that stays
stopped; only a hang-up of the POST /execute call cancels it (see above). A run whose row is gone by the time the move is tried answers 404.
A streaming design run (POST /execute with "stream": true) is stopped
here too: the endpoint asks its consumer worker to end the transfer, waits up to
the same 5s, and answers {"runId": ..., "status": ..., "message": ...,
"totalEvents": N}. The worker owns the terminal write, so the run reaches its
status with its trace and its true event count together, and status is the
one it stored (#3342):
status |
message |
When |
|---|---|---|
stopped |
Stream stopped |
The transfer read the stop; the stream's complete event carries "reason": "stopped" |
completed |
The stream had already ended |
The server had closed the stream, or a cap had ended it, before the transfer read the stop (its post-request script was still running) |
failed |
The stream failed before the stop took effect |
The transfer had already failed |
running |
Stop signalled; the run had not settled within the 5s grace period; read the report |
The worker had not stored a result within the 5s, usually a slow post-request script; the stop still stands |
A stream that had already terminated keeps the reason it recorded rather than being rewritten as a user stop.
Stopping a collection run¶
A sequential collection run (a scenario run, issue #2822) feeds no load
collector, so its answer is read from the summary its worker stores once it has
stopped, the same one the report reads:
{
"status": "stopped",
"runId": "run_1234567890",
"summary": {
"totalRequests": 31,
"errors": 2,
"httpErrors": 2,
"noResponse": 0,
"errorRate": 6.45,
"avgLatencyMs": 12.5,
"stepsExecuted": 40
}
}
totalRequests is requests sent and stepsExecuted is steps, as in the
report: a step the plan skipped is a step and not a request. errors,
httpErrors, noResponse and errorRate come from the stored status-code
distribution over those requests, and avgLatencyMs is the stored latency
block's avg (0 when no step sent). There is no cancelled: a collection
run keeps no count of what its stop cancelled. status is the run's stored
status. A sequential run has no drain, so a Stop always lands while it is
sending and decides the outcome: the run ends stopped.
The summary is absent when the worker has not stored one within the 5s,
or could not store it. The answer is then
{"status": "<stored status>", "runId": ..., "message": "Stop signalled; read
the report"}, usually with status running; when the 5s ran out, message
says so, as for a load run above. The stop still stands: read the
run's report once it reports a terminal status. A scenario load run is a
load run and answers from its collector as above.
GET /runs/:runId/report¶
Get the final report for a completed run. The response is a nested object; conditional
sections appear only when relevant (e.g. rateControl only for constant_rps, testValidation
only when a test script ran, thresholdValidation only when the run declared
budgets, assertions only when a load
run asserted or an element errored, capacity only for a
capacity run, auth only when the run's OAuth 2.0 credential could be
refreshed mid-run, coverage only for a run measured against a bound spec,
schemaValidation only for a run that checked at least one response against
one).
The whole-run aggregates come from the run's stored summary (written once when the run reaches
a terminal status - see db-schema.md), combined with the sampled results
rows for the timing breakdown and the results[] array (at most 100 rows, failures
first - see "results[] is not a uniform sample" below). A run with no summary has either not
reached a terminal status yet (metadata.status is pending or running) or failed without
writing one; its report is built without it rather than erroring. The response shape is the
same either way. A load run the engine died under is marked failed at the next start and
given the totals of its last persisted tick instead (see "A run the engine died under" below).
A report read while the run is pending or running is therefore partial: metadata.status
says the run is still in flight, and thresholdValidation is absent even when the run declared
budgets, because the verdict is computed from the summary written at the end, and
metadata.endTime is null (#2953), not the seed or the 0 the database holds for it. Read
metadata.status before treating a report as final.
A design or scenario run stores its results rows just before its status flips, and a client
fetching once in that gap needs them with their traces, so its partial report is built from the
rows stored so far. A partial report of a load run reads no results row at all (issue
2659): it is the one a client re-reads on a timer, and a load run writes its rows only as it¶
finishes, in chunks (see results), so a report built from them is all
zeros while the run sends and a growing prefix of the flush after. Its figures come from the
run's in-memory counters instead, the ones the live stream reads:
summary.totalRequests, successfulRequests, failedRequests with its httpErrorRequests /
noResponseRequests split, cancelledRequests, errorRate, statusCodes and
errors.byStatusCode, droppedRequests, skippedRequests, stalledMs, peakConcurrency,
avgQueueWaitMs, bytesSent, bytesReceived, httpVersionDowngraded, connectionReplays, and avgRps, throughput,
sendRate and avgInFlight over the time from startTime to the read, which testDuration and
totalDurationSeconds report (#3340). latency is absent, because the percentiles come from histograms the run is
still writing and arrive with the summary. results[] is empty and resultsStored is 0
(resultsCap is unchanged), errors.types is {}, errors.withDetails is 0, and
timingBreakdown and slowRequests are absent. In the moment between the summary write and the
status flip the aggregates are the summary's, as for a finished run, still with no row read. A
run whose row says running but which the engine no longer holds answers the same shape with
every count at zero.
A run the engine died under (issue #2895) is marked failed when the next engine starts
(reconcile_orphaned_runs, see db-schema.md). A load run that persisted at
least one metric tick is given a summary built from its last one, and its
report carries summary.partial: true. The figures are the run's up to that tick:
totalRequests, the success/failure split, errorRate, statusCodes and errors.byStatusCode
(all from the tick's cumulative status distribution), cancelledRequests, testDuration (the
tick's elapsed seconds), avgRps (completions over that time, not the tick's trailing rate),
sendRate, throughput, droppedRequests, skippedRequests, stalledMs, bytesSent and bytesReceived. What the tick does
not measure for the whole run is absent rather than 0: avgInFlight,
connectionReplays, sendingDurationSeconds, completedWhileSending, peakConcurrency and
avgQueueWaitMs (issue #2963), while setupOverhead and httpVersionDowngraded are 0,
sampling is absent, and the report has no latency block (issue #2938): the percentiles come from
the stored results rows, of which such a run has none, so omitting the block says "not recorded"
where a block of zeros would read as steps that answered instantly. A failed load run with no summary at all, because it wrote no
tick or failed on a path that writes none, carries summary.summaryMissing: true, and its
counts are not whole-run totals (those of whatever sampled results rows were stored, often 0) and whose report has no latency block either, even where sampled rows exist, and no peakConcurrency or avgQueueWaitMs. Both keys are absent, never false, on every other report. A client that shows a
figure from a report carrying either one says the figure was not recorded rather than showing it
as measured.
metadata.scenario appears on every collection run, finished or not (issue
3569), and on no other: collectionId, iterations, recursive, the data¶
file's dataFileName / dataFileHash / dataFileCastNumbers and stepCount,
each omitted when the snapshot lacks it. It is the run's snapshot identity,
echoed as the list row's scenario is, and not the top-level
scenario breakdown, which is built from
the stored summary and is absent for a run the engine did not finish. A client
that names a collection run reads it here; the manifest's per-step steps array
is not repeated, only its count.
metadata.openapi appears only for a run whose collection was
bound to a spec when the run was planned (issue #637). It is
echoed from the run's snapshot rather than re-read from the collection: a report
has to say what the run was measured against, and the binding is free to have
moved since. An unbound run carries no openapi key at all - absent rather
than an empty object, so "not measured against a spec" has one spelling.
The binding is resolved by walking from the run's collection up to the root and
taking the nearest bound ancestor, the same walk a single request's
design-mode validation uses (issue #716). An import binds the root and files
every request under tag sub-collections, so running one tag folder is measured
against the document its root binds. When the binding came from an ancestor
rather than from the collection the run named, the node carries
"inherited": true - absent otherwise, like every other finding here. The run
still enumerates only its own subtree, so the coverage below is partial by
construction: most of the contract's operations are honestly uncovered, and
that flag is what lets a reader tell scoped-run truth from a collection that has
stopped calling its API.
coverage says which of that spec's operations the run exercised and which
of their declared responses it saw (issue #629). It is present only for a
scenario run - design or load - of a collection bound to a document that carries
an operation index, and absent, never zeros, for every other
run: an unbound collection, a single-request run, and a document stored before
the index existed all report no block rather than a contract covered zero of.
| Field | Meaning |
|---|---|
operationsTotal / operationsCovered |
Declared operations, and how many got at least one request |
declaredResponsesTotal / declaredResponsesHit / declaredResponseCoveragePct |
Declared status patterns (an x- extension key under responses is not one), and how many the run produced |
undeclaredStatusesSeen |
Distinct (operation, status) pairs the document declares nothing for |
operations[] |
Per operation: sent, statusesSeen, declaredHit, declaredMissed, undeclaredSeen, and transportErrors / otherStatusResponses / statusesTruncated when non-zero |
operations[].statusesTruncated |
Distinct statuses the operation answered with that appear in neither list - the two are capped at 50 each and undeclaredSeen repeats codes from statusesSeen, so this is not the entries the two dropped between them |
transportErrors / undeclaredOperationRequests |
Whole-run findings, present only when they happened |
Rows come back uncovered first - an operation nothing exercised is the
finding - and in document order within each group, so two runs of one contract
print the same way. A status hits the most specific declared pattern that
covers it (exact, then a 2XX range, then default), so an operation declaring
both 200 and 2XX that only answered 200 reports 2XX as missed: those are
two distinct promises. A transport error counts as a request sent and as no
response seen; status 0 is never listed as a status the server sent.
Every number here is exact, not sampled. The engine counts each send and each
response as it happens, through a tally that is not the bounded results[]
store - so a load run whose rows were thinned to a reservoir still reports every
operation it touched. Coverage is computed against the document
metadata.openapi names, at the moment the plan resolved, and stored with the
run; a binding that has since synced to a newer spec cannot rewrite it.
operationsCovered, operationsTotal and declaredResponseCoveragePct are
deliberately plain numbers, shaped like thresholdValidation's counts, so a
headless CI gate can threshold on them without the block being reshaped. Nothing
thresholds on them today.
schemaValidation says whether the responses a run checked matched the
schemas that same document declares (issues #682, #681). It sits beside
coverage and is computed against the same document, but on different evidence,
and the difference is the block's most important field: coverage counts every
send, while this walks whatever the run's mode gave it - the bounded reservoir
of responses a load run stored, or every step a collection run executed.
| Field | Meaning |
|---|---|
sampled |
Responses this pass walked - the denominator for everything else |
checked |
Of those, the ones a declared schema could speak about |
valid / failed |
The partition of checked. valid + failed == checked, always |
unevaluated |
Checked responses whose schema carried a keyword the draft-07 validator could not evaluate (a nested propertyNames included, #2729) |
uncheckedReasons |
Reason code -> count, accounting for every one of sampled - checked |
unevaluatedKeywords[] |
{keyword, count}, so what went unread is named and not only counted |
failures[] |
Bounded examples, at most 10: {step?, status, path, message}. They cover distinct failing steps (the first failure of each, in the order the steps first failed) before repeating one, so a late failing step is not hidden by an early one (#3038) |
failuresTotal |
Every failure found, the cap included - so "3 shown of 90" stays readable |
exact |
true when sampled is the whole population rather than a reservoir - written by a collection run, absent for a load run |
failOnSchemaError |
Whether a schema failure was allowed to fail its step. Collection runs only |
The reason codes are the ones POST /execute's validation
node uses, unchanged.
Under load these numbers are sampled, and nothing here pretends otherwise.
Validation is deferred to run end because a load run refills concurrency on every
completion, so a schema walk on that path would cost throughput for the whole run
- and would do so invisibly. failed: 0 therefore means "no sampled response
failed". sampled is written so a reader always has the denominator; the app
renders it beside the tallies for the same reason.
A collection run writes the same block with exact: true, because it sends
one request at a time and checks every step - there is no hot path to keep off,
so sampled there is the run. The flag exists so a reader is never left to
infer the denominator from the run's mode: the same five numbers are a wider
claim in one than the other, and only the block knows which. A report written
before the flag existed was sampled, which is why absent reads as sampled.
A step's responses are kept when a deferred pass will read them - it carries a
script, or it is bound to an operation and the document carries schemas - and the
run's sample budget is split evenly across those steps. What was displaced is
reported as sampling.response_samples_dropped.
Absent, never zeros, for every run that checked nothing: an unbound collection, a single-request run, a document carrying no response schemas, and a run whose reservoirs held nothing. A run whose responses were never checked did not pass a contract.
Per-step verdicts in a collection run¶
Each step of a collection run carries its own verdict on its stored trace as a
validation node - the same object and the same shape
POST /execute returns - and the live step SSE frame carries
it too, so a run being watched and the same run read back cannot disagree
(issue #681). A step that sent nothing carries no validation at all: there was
no response to judge.
failOnSchemaError is a top-level boolean on POST /runs, default false,
type-checked before the run row is created. It is read by a collection run (a
scenario without a load mode) alone: true on a single-request run or a
scenario load run is a 400 with code invalid_run_config naming the flag,
because those validate sampled responses once the run drains and never fail a
step on them (false and null stay accepted). Left off, a schema failure does not
change any step's outcome: it is its own verdict channel, and a response the
document does not describe is not a failed assertion. Set, a step that passed
everything else and whose response did not match is classified failed, with the
first problem in its results.error; a step already failing keeps the error that
named it. A step failed only by this gate moves scenario.failed (and the run
list's resultSummary.failed), the step's trace outcome and results.error,
and schemaValidation; it does not move summary.failedRequests,
httpErrorRequests, successfulRequests, errorRate, statusCodes (its
200 stays a 200), the maxErrorRatePct input or summary.assertions. Those
are HTTP-only, the same rule a failed assertion follows
(see assertions under Scenario load runs).
Response:
{
"metadata": {
"runId": "run_1234567890",
"runType": "load",
"status": "completed",
"startTime": 1234567890,
"endTime": 1234567950,
"requestUrl": "https://api.example.com/users",
"requestMethod": "GET",
"configuration": {
"mode": "constant_rps",
"duration": "60s",
"concurrency": 100,
"targetRps": 100,
"followRedirects": true,
"maxRedirects": 10,
"httpVersion": "auto",
"dataRowCount": 2,
"dataFileName": "users.csv",
"dataFileHash": "<sha256>",
"dataFileCastNumbers": true,
"carriedBudgets": ["latencyP99Ms"],
"acceptEncoding": true,
"expectContinue": false
},
"openapi": {
"specId": "spec_3f2b1c9a-...",
"specHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
},
"summary": {
"totalRequests": 6000,
"successfulRequests": 5970,
"failedRequests": 30,
"httpErrorRequests": 20,
"noResponseRequests": 10,
"cancelledRequests": 0,
"errorRate": 0.5,
"totalDurationSeconds": 60.4,
"avgRps": 99.34,
"testDuration": 60.4,
"sendRate": 100.0,
"throughput": 99.34,
"setupOverhead": 0.12,
"cleanupOverhead": 0.03,
"peakConcurrency": 100,
"droppedRequests": 0,
"skippedRequests": 0,
"stalledMs": 0,
"avgQueueWaitMs": 0.4,
"avgInFlight": 4.2,
"bytesSent": 192000,
"bytesReceived": 7680000,
"throughputBytesPerSec": 127152.32,
"httpVersionDowngraded": 0,
"connectionReplays": 0,
"sendingDurationSeconds": 60.0,
"completedWhileSending": 5990
},
"latency": {
"min": 12.3, "max": 1250.5, "avg": 42.1, "median": 38.5,
"p50": 38.5, "p75": 45.2, "p90": 78.3, "p95": 95.1, "p99": 156.7, "p999": 450.2
},
"statusCodes": [[0, 10], [200, 5970], [500, 20]],
"rateControl": { "targetRps": 100, "actualRps": 100.0, "achievement": 100.0,
"requestsSent": 6000, "requestsExpected": 6000 },
"errors": {
"total": 30,
"withDetails": 10,
"types": { "timeout": 6, "connection_failed": 4 },
"byStatusCode": [[0, 10], [500, 20]]
},
"timingBreakdown": {
"avgDnsMs": 0.15, "avgConnectMs": 0.42, "avgTlsMs": 0.31,
"avgFirstByteMs": 3.1, "avgDownloadMs": 0.14,
"phases": {
"dns": { "p50": 0.1, "p95": 0.2, "p99": 1.4, "max": 12.0, "count": 6000, "mean": 0.15 },
"connect": { "p50": 0.3, "p95": 0.9, "p99": 8.2, "max": 40.1, "count": 6000, "mean": 0.42 },
"tls": { "p50": 0.0, "p95": 0.0, "p99": 22.0, "max": 61.0, "count": 6000, "mean": 0.31 },
"firstByte": { "p50": 2.9, "p95": 4.0, "p99": 6.1, "max": 30.0, "count": 6000, "mean": 3.1 },
"download": { "p50": 0.1, "p95": 0.3, "p99": 0.9, "max": 4.2, "count": 6000, "mean": 0.14 }
}
},
"slowRequests": { "count": 12, "thresholdMs": 1000, "tracesStored": 12, "percentage": 0.2 },
"warnings": [
{ "code": "unresolved_tokens",
"message": "12 requests sent with unresolved variables: token",
"count": 12, "names": ["token"] },
{ "code": "pre_request_script_skipped",
"message": "1 step carries a pre-request script that does not run under load",
"steps": 1 },
{ "code": "cookies_dropped",
"message": "4 Set-Cookie headers were dropped across the run by libcurl's cookie engine (a line over 5000 bytes, a name and value over 4096 bytes, or more than 50 in one response), so the virtual users that received them sent their later steps without those cookies.",
"count": 4 }
],
"stream": { "...": "streaming runs only - see below" },
"sampling": {
"errorsDropped": 0, "successTracesDropped": 29000,
"slowTracesDropped": 0, "responseSamplesDropped": 998000,
"exemplarsDropped": 0, "sampleBodiesDropped": 12,
"responseBodiesCaptured": 23, "responseSampleBudgetSpent": false
},
"monitor": {
"samples": 58, "failures": 2, "noMatchScrapes": 0, "lastError": "timed out",
"series": {
"node_cpu_seconds_total": { "min": 1.2, "max": 3.9, "avg": 2.6, "count": 58 }
}
},
"testValidation": {
"samplesTested": 500, "testsPassed": 498, "testsFailed": 2, "successRate": 99.6,
"console": [ { "level": "warn", "text": "cache miss for /users", "count": 412 } ],
"consoleDropped": 3
},
"thresholdValidation": {
"checks": [
{ "metric": "latencyP99Ms", "limit": 50, "actual": 47.2, "passed": true, "evaluated": true }
],
"passed": 1, "failed": 0, "verdict": "passed"
},
"assertions": {
"exact": { "passed": 0, "failed": 0 }, "sampled": { "passed": 498, "failed": 2 },
"errored": 0, "teardownFailed": 0
},
"customMetrics": {
"ttfb2": { "type": "trend", "count": 42, "p50": 10.0, "p95": 40.0, "p99": 47.0, "max": 50.0 },
"bytesOut": { "type": "counter", "count": 4, "value": 4096.0 },
"cacheHit": { "type": "rate", "count": 10, "value": 30.0 }
},
"auth": { "refreshes": [ { "atSeconds": 3620.4 } ], "refreshFailures": 0 },
"coverage": {
"operationsTotal": 18, "operationsCovered": 14,
"declaredResponsesTotal": 41, "declaredResponsesHit": 29,
"declaredResponseCoveragePct": 70.7, "undeclaredStatusesSeen": 1,
"operations": [
{ "operationId": "deletePet", "method": "DELETE", "path": "/pets/{petId}",
"sent": 0, "statusesSeen": [], "declaredHit": [], "declaredMissed": ["204"],
"undeclaredSeen": [] }
]
},
"schemaValidation": {
"sampled": 40, "checked": 36, "valid": 30, "failed": 6, "unevaluated": 0,
"uncheckedReasons": { "body_not_json": 4 },
"failures": [ { "step": "get pet", "status": 200, "path": "/id", "message": "Value type not permitted by 'type' constraint." } ],
"failuresTotal": 6
},
"lifecycle": {
"setup": [ { "id": "el_setup1", "kind": "script.setup", "outcome": "ok" } ],
"teardown": [ { "id": "el_teardown1", "kind": "script.teardown", "outcome": "error", "message": "Error: boom",
"messages": [ { "kind": "error", "text": "Error: boom" } ],
"console": [ { "level": "log", "text": "tearing down" } ] } ]
},
"elements": [
{ "id": "el_1", "kind": "assert.status", "name": "Is 200",
"passed": 9, "failed": 1, "missing": 0, "error": 0, "skipped": 0, "deferred": 0 },
{ "id": "el_2", "kind": "extract.json", "required": true,
"passed": 8, "failed": 0, "missing": 2, "error": 0, "skipped": 0, "deferred": 0 },
{ "id": "el_3", "kind": "script.post",
"passed": 0, "failed": 0, "missing": 0, "error": 0, "skipped": 0, "deferred": 10 }
],
"results": [ { "id": 41, "...": "request/response outcomes, failures first" } ],
"resultsStored": 4812,
"resultsCap": 100
}
Two clocks, and which rate reads which (issue #2392). testDuration (and
totalDurationSeconds, the same figure) is the wall time from load start - the
instant of the first submission - to the last request settling, so it includes
the end-of-run drain, in which requests still in flight at the deadline are let
answer (up to the run's effective timeout, its timeout or else the
defaultTimeout setting, plus a grace, except a streaming run, whose bound is
its maxStreamDurationMs plus grace). avgRps and throughput are
completed requests over that wall time: they describe what the target served,
and a run whose requests outlive its deadline reads below its target there by
design. sendRate and rateControl describe what the generator sent, and
divide by sendingDurationSeconds: load start to the moment the run stopped
submitting, before the drain. completedWhileSending (issue #2882) is the
requests completed by that same moment, so it is never above totalRequests,
and completedWhileSending / sendingDurationSeconds is the response rate
while sending, the figure to hold beside sendRate; throughput counts the
drain in both its completions and its seconds. A run whose few slow
requests time out long after the sending ends reads a throughput far below
that rate; a run whose every request takes the same time reads a little
above it, because the drain answers the requests the sending window left in
flight. rateControl.achievement is
requestsSent / requestsExpected x 100, the pacer's own count with
requestsExpected = targetRps x duration, and rateControl.actualRps is
requestsSent / sendingDurationSeconds. rateControl.requestsSent and
requestsExpected are the run totals behind the live metrics frame's fields of
the same name. A shortfall there is not only a slow generator: a request
dropped at the maxInFlight cap (droppedRequests) was never sent, a request a
stalled pacer skipped (summary.skippedRequests, with the schedule time they
cover in summary.stalledMs) was never sent either, and a Stop
ends the sending early, so a stopped run's achievement is the share of its plan
it reached. The app's Rate fidelity card instead divides by what the target
owed up to now (targetRps times the time spent sending, capped at the
duration; once the sending window is over, the engine's whole count
floor(targetRps x duration), so 33.3 RPS over 3 s ending at 99 sent reads
100), so on a Stop it reads the pace. It does so live, and for a stopped
run in History from requestsSent, sendingDurationSeconds and the configured
duration (issue #2805), while the stored rateControl.achievement stays the
plan share and the card states it beside the figure ("stopped at 50% of the
planned 60s"). A stopped report without the counts keeps its stored value.
Skips lower the achievement and are shown beside it (issue #2911).
summary.skippedRequests is the requests a constant_rps pacer owed beyond its
100 ms catch-up window and chose not to send after a stall of the load generator
itself, and summary.stalledMs the schedule time they cover
(skippedRequests ÷ targetRps, in ms). They are the run's totals, stored as
skipped_requests / stalled_ms in the summary and on every
metric tick, and read as 0 from a summary stored before them (the run skipped
nothing, it had no cap to skip under). rateControl.achievement is not adjusted
for them: a skipped request was owed and never sent, so requestsSent /
requestsExpected is the honest share of the plan, and the two counters are what
tell a stall from a slow target. sent + skipped + dropped is
requestsExpected for a run that reaches its deadline. The run
export carries both in report.summary (optional in its
schema, absent from a document written before them); its Markdown and HTML
renderings print them as one Skipped requests row of the results table when
skippedRequests is above 0, apart from maxInFlight drops, which they do not
print (droppedRequests has no row).
An iterations run, single-request or scenario, is the one exception: its
loop returns on its last submission with the batch before it still in flight,
so a window measured to that point would overstate the rate it sustained. Its
sendingDurationSeconds is its whole testDuration and its
completedWhileSending its totalRequests, unless a Stop ended it, in which
case the measured window and the count at its end stand. A run stored before
issue #2392 has neither sendingDurationSeconds nor the two counts: its
sendRate divided by testDuration, and its rateControl keeps the formula
it was stored with, actualRps the completed rate and achievement =
actualRps / targetRps x 100. A run stored before issue #2882 has no
completedWhileSending, never a 0.
statusCodes and errors.byStatusCode are [[code, count], ...] pairs on
the wire, in ascending code order, not objects: each is a std::map<int,
size_t>, which nlohmann serialises that way. The app folds the pairs
(run-report-transformer.ts) and the MCP comparison reads either form
(statusCodeEntries). The stored summary, a live metrics frame and the
document POST /export/run-report writes all spell
the distribution as an object.
errors is the run's failures three ways. total is the
one error definition and byStatusCode its
distribution, code 0 being the requests that got no response. types counts
those no-response requests by what went wrong (timeout, connection_failed,
dns_failed, ...), so its counts sum to byStatusCode's code 0. For a load
run, a collection load run included, they are counted as the run happened and
stored in its summary (issue #2400), exact past the error store's cap.
withDetails is how many error records the run kept, at most
maxStoredErrors, so past the cap it is smaller than types adds up to.
Load runs stored before issue #2400, and design-mode collection runs, have no
stored per-type counts: their types counts the kept records, and past the cap
covers only the first maxStoredErrors errors.
slowRequests is present when the run set a slow_threshold_ms above 0.
count is every successful completion at or past thresholdMs, counted as it
happened (issue #2399), and percentage is count over
summary.totalRequests - a denominator that includes failed requests, although
only a success is ever marked slow. tracesStored is how many of them the run
kept a trace for: the slow store is a reservoir capped at max_slow_results, so
past the cap count - tracesStored is what the reservoir dropped
(sampling.slowTracesDropped). count: 0 is a run that measured and found
nothing slow. A run stored before issue #2399 has no exact count in its summary,
so its count is the stored traces again (equal to tracesStored, and never
past the cap), and the section is absent when none of its traces was slow.
elements (issues #1594, #1641) is a single-request run's own requestElements
outcomes - extract.* / assert.* / timer.* / script.*, tallied across every
submission in the row shape a scenario step's elements uses ({id, kind, name?, origin?,
required?, passed, failed, missing, error, skipped, deferred}, one count per outcome word,
3051; see Scenario load runs), and an inline script.* row's¶
messages?, messagesDropped?, console? and consoleDropped?: what it threw, each
failing test and its console lines, a bounded distinct sample (#3127, described there).
There is one row per element,
in requestElements order, so a collection's element and the request's own that share an
id (#3101) are two rows, each with its own counts and origin. deferred (issue #2144)
counts the submissions an un-inlined script.post was left to the completion replay on:
its verdicts are the report's testValidation, drawn from the sampled responses, so it is not a
script that never ran. skipped is every other skip: a disabled element, an un-inlined
script.pre, an optional extract.json over a body it could not read, or an inline
script.* the run's Stop cut short, its pm.sendRequest cancelled (#3371) or the script itself ended (#3460). Absent, not [], for a run that declared no
requestElements, one whose elements never ran, and every scenario run - a scenario's
own per-step tallies live under scenario.steps[].elements instead (see
The scenario block and
Scenario load runs), and the two never coexist on one report.
testValidation counts in two units: samplesTested is a number of responses
(each sampled response the post-run replay evaluated the plan's script.post against),
while testsPassed and testsFailed are numbers of assertions (pm.test calls) across
those responses, so testsPassed + testsFailed is not samplesTested once a script holds
more than one assertion. successRate is testsPassed as a percentage of assertions.
samplesTested is also not summary.totalRequests: the replay buffer is bounded
(sampling.responseSamplesDropped) and a request with no response has nothing to test.
console? and consoleDropped? (#3127) are what the replayed scripts logged, in the element
row's console shape ([{level, text, count?}]): the first 10 distinct lines across every
sample, each cut to 500 bytes, kept whatever the script's verdict and with count when it
was logged more than once (absent means once), and the count of occurrences a full list
turned away. Both are absent when the replay logged nothing (consoleDropped also when
nothing was turned away), and on a scenario load run, whose replay keeps one list per step
on scenario.steps[].tests instead, so one step's line is never
merged into another's.
The failing assertions are named on one synthetic row of results[], the one whose trace
carries failures (no captured request has it): failures (each distinct message once, at most
10, a scenario step's name prefixing it), failureCounts (how many times each failed),
failuresDistinct (every distinct message, so failuresDistinct - failures.length were turned
away), totalFailed and totalPassed (assertions, each occurrence counted). A script failing
the same way on every sampled response is one entry with a count, not one entry per sample
(#3127). failureCounts and failuresDistinct are absent on a row from an older engine; see
results for the stored shape.
thresholdValidation is one check per declared
budget with the run's verdict. A
maxAssertionFailureRatePct check also names the two populations it judged
(issue #2892): assertionsSampled is testValidation's testsPassed and
testsFailed, at sampleRate, and assertionsExact is the inline
assertions counted on every completion that testValidation does not see.
actual is the worse of the two failure rates.
assertions (issue #3537) is every failed check a load run's verdict
reads, in one shape for both load run kinds, judged or not:
| Key | Meaning |
|---|---|
exact |
{passed, failed}: every assert.* outcome, required extract.* miss and inline pm.test call, counted on each completion. A maxAssertionFailureRatePct check's assertionsExact, and a scenario load run's scenario.assertions |
sampled |
{passed, failed}: the deferred replay, testValidation's testsPassed and testsFailed. A replayed script that threw is one failed test here |
errored |
Element executions that ended in error: an inline script that threw, an element that could not run. The summed error of the elements rows (a scenario load run's scenario.steps[].elements), never scenario.errored, which also counts a step with no response |
teardownFailed |
The lifecycle.teardown rows whose outcome is failed or error. A failed setup fails the run instead |
Absent for a run that made no assertion and errored nowhere, and for a
sequential collection run. A run stored before the block gets one derived from
what it stored, carrying only what the readers then read: a scenario load run's
scenario.assertions as exact, a single-request run's assert.* and
script.* element rows as exact and its testValidation as sampled, never
errored or teardownFailed. A member it could not derive is absent, not 0.
customMetrics (issue #1500) is this run's metric.record / pm.metrics values, by name -
absent, not {}, for a run that recorded none. A "trend" entry carries count/p50/p95/p99/
max; a "counter" or "rate" entry carries count and value (a running total, or a 0-100
percentage). count is always how many times the name was recorded: a trend's samples, a
counter's records (four increments of 1024 are count: 4, value: 4096, never the total; #1937),
a rate's evaluations. A counter's increments are finite and never negative - see
custom.<name>.<stat>. The same shape rides every
GET /runs/:runId/metrics tick,
and custom.<name>.<stat> reads it for a threshold.
timingBreakdown averages every completion. phases comes from five
HdrHistograms fed by every successful completion, and each phase carries its
mean beside its percentiles; the avg* fields are those means (issue #2782),
so avgTlsMs and phases.tls.p99 describe the same completions, and the last
live gate frame's cumulativePhases means equal them.
phases is absent when phaseHistograms was off, nothing succeeded, or the run
predates the bank. Without it, and for a run stored before the means existed
(its phases carry no mean), the avg* fields fall back to the run's
retained trace sample - the 1-in-success_sample_rate completions stored
while save_timing_breakdown is on, plus any slow-request outliers - and are
absent for a run that stored no traces. Read each half by its own key: the
object's presence proves neither.
phases is what answers "was the latency the server or the connection path".
A tls.p50 of 0 beside a large tls.p99 is a run re-handshaking under load -
most requests reused a connection, a minority did not - which the average over
both flattens into a number that looks merely mediocre. count is the number of
completions behind each distribution and is identical across the five.
warnings (issue #1503) is what the run did not do, even though it
finished and its other numbers may look fine: a request sent with a
{{token}} composition never resolved (a scenario load run, and a
single-request run that declares requestElements, re-resolve what
composition left against the executing virtual user's or submission's own
scopes before sending, so a name an inline script or extractor set is
answered; a single-request run without requestElements resolves its request
once, at run start, against the scopes an environmentId or requestId
names, and runs no pass at all when it names neither, so either way a value a
pre-request script would have set goes on the wire literally), or a step whose pre-request script this mode never executes -
one that did not run inline (issue #1938: elements.scripts: "allInline", or
the element's own inline: true under asMarked, runs it and raises no
warning). Neither refuses the run - a literal {{ can be deliberate in a body -
they are counted, not fixed. Each entry carries code and a human-readable
message; unresolved_tokens also carries count (requests affected) and
names (a few of the unresolved names, capped); pre_request_script_skipped
carries steps (how many carried a script.pre that did not run inline).
per_host_limit_raised (#2394)
is of another kind: the run did everything, but opened more connections per
host than eventLoopMaxPerHost says, because each worker's share of the
virtual users (ceil(concurrency / workers)) was larger; it carries
configured (the setting) and effective (the per-host limit each worker ran
with). It appears only when the run asked for virtual users, a config that
carries concurrency (#2801): a
run that sets none is sized from the eventLoopMaxConcurrent default and gets
the same raise, but has no virtual users to cover and no warning about them.
connection_replayed (#2799) is
another: libcurl re-sent count requests on a new connection after the
server dropped or refused a reused one before answering, so the target
received that many more requests than the run counted, each of those
requests' latency covers both attempts, and a non-idempotent one may have run
twice; count equals summary.connectionReplays, and it is raised only when
that is above 0 (see What counts as an error).
cookies_dropped (#3307) means
libcurl's cookie engine discarded count Set-Cookie headers from the run's
responses, summed over every response and redirect hop: a line over 5000 bytes,
a cookie whose name and value pass 4096, or one past the 50th of its response,
the limits a design send reports per cookie (see Cookies). A
virtual user that lost a session cookie this way sent its later steps without
it. The message names no cookie. Only a scenario load
run's steps carry cookies, so only it can raise this; a step with
disableCookies drops nothing. The outgoing caps (a Cookie line over 8190
bytes, more than 150 jar cookies) are not detected under load: reading libcurl's
notice needs CURLOPT_VERBOSE on every transfer.
think_timer_skipped_open_loop (#3541)
is raised once by a constant_rps single-request run that sent anything and
whose requestElements hold an enabled timer.think: the pacer sends on a
schedule, so the timer was skipped on every submission (each tallied skipped
under summary.elements) and held no slot. Its message is "A think timer
does not apply to a constant-rate run: requests are sent on a schedule, not
one after another", and it carries timers (how many enabled timers were
skipped). A closed-loop mode runs the timer and raises nothing.
Absent, not an empty array, for a run
with nothing to report - which is every run before this field existed and
every run that genuinely had nothing to say. unresolved_tokens covers every
load shape alike (issue #1540): a single-request run with no data set and a
scenario step report the same warning for the same mistake.
lifecycle (issue #1499) is script.setup / script.teardown's outcomes -
what ran once at the run's own boundary, never at a step. Each key is present
only when that phase ran at least one element (ElementOutcome's usual shape:
id, kind, name?, origin, outcome, message?, waitedMs?, plus the two lists
below); absent entirely,
not {}, for a run whose collections (or, for a single-request run, whose own
lifecycleElements array - issue #1573) declared neither. A collection run's
elements come from its lifecycle set (#3456): every collection from the root
down to the one being run and, on a recursive run, every folder beneath it in
sidebar order, a folder before the folders nested in it. setup lists them in
that order and teardown in reverse, and each row's origin is
{kind: "collection", scope: "collection" | "folder", id, name}, naming whose
script it was. A script.setup outcome
other than "ok" or "skipped" means setup refused the run before it sent
anything: status is Failed, no step ran, and the run still stores a summary
whose lifecycle.setup holds every setup that ran up to and including that
outcome with its message (#3455), every
other section above absent or zeroed - so a reader who finds one here knows why
the rest of the report is empty. The collections after the refusing one set up
nothing. No teardown runs on such a run, so it has no
teardown key. A script.teardown
outcome of "error" carries the thrown message but never changes status: a
teardown failure is reported, not fatal. A script that ran and failed only
pm.tests is "failed", its message the first failing test, as a script.post's is.
A script element's row also carries messages (what it threw, then each
failing test, as {kind: "error" | "test", text}) and console (each
console line, as {level, text}) - the entry shape, the cap of ten distinct entries,
the count on a repeat and the messagesDropped / consoleDropped counts of an
element row's lists (#3127), each key present only when the script said something.
A script the run's Stop cut short is
"skipped", with a message saying which way: its pm.sendRequest was
cancelled (#3371), or the script itself was ended while it ran (#3460). The run
ended under it, nothing failed, and the app shows the row muted rather than as a
failure.
A streaming run adds a stream section and no other run carries one:
"stream": {
"completions": 480,
"totalEvents": 19200,
"capped": 480,
"eventsPerSecond": 320.0,
"events": { "min": 40, "max": 40, "p50": 40, "p90": 40, "p95": 40, "p99": 40, "count": 480 },
"timeToFirstEvent": { "p50": 412.0, "p95": 655.0, "p99": 803.0, "max": 910.0, "count": 480 }
}
Absent for every run that did not stream, and for one started with
stream_metrics: false - not zeroed, because "this run was not a stream" and
"this stream delivered nothing" are different answers, and a run whose target
closed every connection before the first event is where telling them apart
matters.
events is the per-completion distribution, not the run's total: 480
streams of 40 events each have a p50 of 40, not of 19200. eventsPerSecond is
the whole-run rate, derived from the same testDuration the report's rps
uses so the two are comparable. Both are reported because one long stream and
250 short ones can share a rate while being entirely different runs.
A stream that delivered nothing is a 0 in events like any other count
(#3240), so a run whose target closed every connection before the first
event reads min, max and every percentile as 0 beside totalEvents: 0.
The figures are exact up to 2,046 events per stream and within 0.1% above.
capped counts the completions a cap ended rather than the server. In the
example above every stream hit the event cap - the events percentiles all
sitting exactly on it is the tell - so those counts measure the caps, not the
target.
timeToFirstEvent (issue #3234) is the per-completion distribution, in
milliseconds, of how long each stream took to deliver its first event: from
the moment the request was submitted, the origin latency is measured from,
to the write that completed the first frame carrying a data field. It is not
timingBreakdown.phases.firstByte, which ends at the response headers: an LLM
gateway answers 200 at once and then thinks, so its wait lands in the
download phase and firstByte reads fast for a stream whose first token was
slow. count is the completions that delivered an event, so a stream the
target closed before its first event, a silent one a cap ended, and one whose
only event was an unterminated frame the close completed are all left out (the
last arrived at the close, and no time for it was measured). The object is
absent when no completion delivered a timed event.
A capacity run adds a capacity section and no other mode carries one:
"capacity": {
"sloMs": 200,
"maxErrorPct": 1,
"stopReason": "slo_exceeded",
"maxHealthyConcurrency": 48, "maxHealthyRps": 23400, "p99AtMaxHealthyMs": 41.2,
"kneeConcurrency": 64, "kneeP99Ms": 312.0, "kneeErrorPct": 0.4,
"levels": [ { "concurrency": 1, "rps": 980, "p99Ms": 1.4, "errorPct": 0, "samples": 4900 } ]
}
stopReason is one of slo_exceeded, errors_exceeded, plateau,
cap_reached, deadline or stopped - see Capacity semantics.
maxErrorPct is the error-share limit each level was judged against, and
errorPct / kneeErrorPct are percentages (0-100) on the same scale, so a
reader can mark an over-limit level without knowing the constant. The optional
groups are omitted rather than zeroed, and the distinction carries
information:
maxHealthy*is the highest level tried that stayed inside the budget, and is absent when the very first level already breached it (on latency or on errors). The search found no sustainable capacity, which is not the same claim as a capacity of zero. On aplateaustop it is the last level tried, which overshoots: readsaturation*for the plateau.knee*is absent unlessstopReasonisslo_exceededorerrors_exceeded. A run that ended at its ceiling, its deadline, or on a plateau inside the budget never watched the target give out, so it has no knee to report.saturation*(saturationConcurrency,saturationRps,saturationP99Ms) is present only whenstopReasonisplateau: the lowest healthy level whose throughput the best healthy level beat by under 5%, i.e. where more concurrency stopped buying work. A run that stopped any other way never observed a plateau and carries none.maxErrorPct,kneeErrorPctandlevels[].errorPctare absent from a run stored before the search judged errors (#2815): it never measured an error share, and a 0 would call every level clean.levels[].samplesis the number of completions the level's histogram held when the level was judged (#2926), i.e. whatp99Mswas computed over. A0means the level measured no latency (only refused connections), so itsp99Msof 0 is "nothing measured", not "answered instantly". It is absent from a run stored before the field existed, never0, for the same reason as the error share.
levels[] is one entry per level judged, in order - bounded by construction
(a search holds tens of levels, not thousands). A level that breached once and
was re-measured appears twice, at the same concurrency; the level still being
measured when the run ended does not appear at all, because it was never judged.
auth appears only for a run whose OAuth 2.0 credential could be renewed
while it ran - a header-placed, expiring token with autoRefreshToken on (see
db-schema.md for the full eligibility list). Each
entry in refreshes is when a renewal landed, in seconds from the run's start.
refreshFailures plus a lastError string is the other half of the answer: the
run kept sending the credential it had, so 401s in statusCodes from that point
on are explained here rather than by the target. A renewal still in flight when
the run ends is cancelled rather than waited out, and is not a failure. The
section is absent for a run that could never refresh, which is not the same
claim as a run that watched and never needed to (that one reports an empty
refreshes array). A collection
load run that keeps several tokens current (one per distinct cache key its steps
send, #3199) reports them in this one shape: every renewal in refreshes, in
order of atSeconds, refreshFailures summed, and lastError the most recent
failure of any of them.
A scenario run adds a scenario section and no other run type carries one:
"scenario": {
"iterations": 3, "iterationsCompleted": 3, "stepsExecuted": 6,
"passed": 4, "failed": 1, "skipped": 0, "errored": 1,
"stepsStored": 6, "stepsDropped": 0, "stepsNotRun": 0, "stopOnError": false,
"stopped": 0,
"transactions": [
{ "name": "checkout", "count": 3, "errors": 0,
"latency": { "min": 8.1, "p50": 14.2, "p90": 22.0, "p95": 26.5, "p99": 33.0, "max": 55.4 } }
]
}
stepsStored versus stepsExecuted is the honest reading of results[]: a run
that filled maxScenarioStoredSteps reports fewer rows than it ran, with every
failed, errored and skipped step among the ones kept (a stopped one is kept
like a success). On a collection run (design mode)
stepsExecuted counts steps and summary.totalRequests counts requests
sent (issue #2822): a step the plan skipped (control.if,
control.throughput, pm.execution.skipRequest()) is a step and not a request,
while a request that got no response is one, under status 0. statusCodes,
successfulRequests, failedRequests and errorRate come from the
distribution the runner stored over those same requests, never from the kept
rows, where a skipped step is a status-0 row: they describe the whole run past
maxScenarioStoredSteps and agree with a maxErrorRatePct check's actual. A
run in which every step was skipped reports totalRequests 0 and an empty
statusCodes. A summary stored before #2822 has no distribution: its
totalRequests is the step count and the split comes from the kept rows.
passed, failed, skipped and errored mean the same in both run kinds
(#2824, the Outcomes table under Scenario runs): one per step
execution, disjoint, with an HTTP error status that no assertion rejected
counted as passed and in summary.failedRequests. stepsExecuted is every
step reached, a skipped one included, so in both
passed + failed + errored + skipped + stopped = stepsExecuted, stopped
read as 0 where it is absent. A scenario load run's
steps[].executed counts every execution that was not skipped, so there the sum of
steps[].executed, plus skipped, also equals stepsExecuted; a collection
run has no steps array. A scenario load run stored by engine 0.45.0 or
earlier keeps its old numbers: failed was the sum of every step's
httpErrors, and passed was stepsExecuted less failed and errored,
skipped steps included.
stepsNotRun is how many plan positions errors cost the run - summed over
every iteration an errored step ended, the positions after that step the
iteration had not attempted (Outcomes under Scenario runs).
stepsExecuted beside a non-zero stepsNotRun is a run that did less than its
plan, not a complete one with an error in it. stopOnError is the run's own
setting, echoed because the same counts describe a different run under it.
Both are written by a collection run (design mode) only: a scenario load run's
section carries neither, and a summary stored before issue #2526 carries
neither either. stopped (#3397) is the steps a Stop or a shutdown cut short,
which no failure count includes and which take no failure's place among the
kept rows; it is likewise a collection run's alone, absent for a scenario load
run (whose stop-cancelled steps are in no count) and for a summary stored
before it.
assertions (#2820) is the other way round: a scenario load run's alone,
{ passed, failed } over the exact population (every assert.* outcome,
required extract.* miss and inline pm.test call, never the sampled replay
testValidation reports), the report's top-level assertions.exact. It
counts assertions where failed above counts step executions, so an
execution that failed three is one failed step and
three assertions.failed. It is absent for a run that made no such assertion, a collection run in
design mode and a run stored before it; Scenario load runs
has the rest.
transactions (issue #1515) is a sibling of steps, not a member of it - a
control.transaction spans a folder, not one step - and is absent, never
[], for a run with no control.transaction element or one whose folder
never closed. One entry per declared name that closed at least once, in the
same shape scenario.transactions documents elsewhere on this page.
latency.* and the enriched summary fields (peakConcurrency, avgInFlight, droppedRequests,
skippedRequests, stalledMs, avgQueueWaitMs, bytesSent/Received, throughputBytesPerSec) come from the run's stored
summary, not from the per-tick metrics rows. latency_ms in results is perceived
latency.
A collection run's summary omits the load-only figures (issue #2822). A
sequential run feeds no load collector, so sendRate, throughput,
peakConcurrency, droppedRequests, avgQueueWaitMs, bytesSent,
bytesReceived, throughputBytesPerSec, setupOverhead and cleanupOverhead
are absent rather than 0; avgRps is requests sent over testDuration. A
scenario load run is a load run and carries every one of them.
A collection run's latency block (issue #2389) is the stored latency its runner wrote,
over the latency population of the sequential path: every step whose
transfer ran, answered or not, and not a step the plan skipped or one refused before the wire.
That is the sample the run's latency*Ms budgets
judge, from one computation, so latency.p99 equals the actual of a latencyP99Ms check.
Unlike the HDR histogram the load paths read, the figures are exact nearest-rank over the
full sample (avg is its mean), and they are not read from the results[] rows, which can
include a skipped step's 0 ms and are thinned past maxScenarioStoredSteps. A collection run
in which no step sent has no latency block rather than zeros. A summary written before
this existed carries no latency and reports from the stored rows as before.
summary.failedRequests and summary.errorRate are the
one error definition, recounted from the run's
status-code distribution; summary.httpErrorRequests and
summary.noResponseRequests split failedRequests and always sum to it.
summary.totalRequests is successfulRequests + failedRequests, the requests
that got an outcome, and errorRate is failedRequests over it.
summary.cancelledRequests is the requests a POST /runs/:runId/stop
cancelled before they answered (issue #2136): sent, never an outcome, and so
in none of the figures above - a healthy target stopped mid-run reports
errorRate 0 beside them. Always present: 0 for a run nothing cancelled,
and for a run whose stored summary predates the count, because only the
stored summary records it (the status-code distribution never held them).
summary.drainCut ({cancelled}, issue #3538) is present only when a Stop
cut the drain of a run that ended on its own: the part of cancelledRequests
still unanswered when the drain was stopped, which keeps the run's verdict
not judged unless a budget already failed it.
summary.partial (true) marks a run the engine died under, whose figures are
its last persisted tick's; summary.summaryMissing (true) marks a failed load
run with no summary at all, whose counts are not a measurement. Neither report has
a latency block (issue #2938). Each flag is absent otherwise, never false; "A run the engine died under" above says what each
figure then holds.
summary.httpVersionDowngraded is the count of this run's transfers that asked
for HTTP/2 and negotiated something older - see
httpVersionDowngraded on a response. A collection run counts
its sent requests the same way (#3262, Scenario runs); a
collection run stored by an engine older than that fix reads 0 here although
its steps' traces may say otherwise. It is the only figure in
summary that describes the report's validity rather than its performance:
non-zero means the latency and throughput beside it were measured over a
protocol other than the one metadata.configuration.httpVersion names.
0 is "none recorded", not "none happened". An engine from 0.15.0 always
emits the key - including for a run whose stored summary predates the count, and
for one reported from its sampled results because that summary was malformed or
never written, neither of which can produce a figure. The key is absent only
from an engine older than 0.15.0. That is deliberately a weaker guarantee than
the per-response httpVersionDowngraded, which is exact for the exchange it
describes.
summary.connectionReplays is the count of requests libcurl re-sent on a new
connection after the server dropped or refused a reused one before a byte of
the answer (issue #2799). The extra sends are in no other count, not
totalRequests, the error counts or noResponseRequests: each replayed
request is counted once, by the outcome of its last attempt, so the target
received totalRequests +
connectionReplays requests (see
What counts as an error). A non-zero value also
raises the connection_replayed warning. Absent and 0 are different
answers: 0 is a run whose engine counted and saw none (the key is always
stored, zero included), and absent is a run stored before the count existed,
or one reported from its sampled results because its summary was malformed or
never written. A partial report of a running load run reads it from the live
counter.
summary.avgInFlight is the mean number of requests in flight over the run
(issue #2821): the time requests spent in flight, summed over every request,
divided by testDuration (issue #3567). A request is in flight from its
submission to the event loop until it completes, its queue wait inside the
generator or libcurl included, and a Stop's cancellation ends it, so a request
the Stop cancelled counts the time it was open. A virtual user in a timer wait
between requests has none, and neither does a request refused or skipped
before it reached the event loop (a maxInFlight drop, a data-binding
failure, a step a controller skipped). A step's script time (elements.includeScriptTime)
is not part of it. With no think time it equals the virtual user count, and
over that count it is the run's utilisation. A run stored before issue #3567
keeps the old figure under the same key: the latency sum of the
latency population divided by testDuration, which
left out cancelled requests and folded in included script time. peakConcurrency beside it is the high-water mark of the
instantaneous in-flight gauge (the live stream's backpressure), which the load
generator reads after each batch of submissions in every mode: the closed-loop
controller behind constant_concurrency, ramp_up, iterations, capacity
and every scenario run, and the open-loop pacer behind constant_rps (issue
2912). The once-a-second metrics sample is a backstop writer. A¶
closed-loop single-request run's gauge counts the slots a timer.think wait
holds too; a constant_rps run's counts requests alone, because it skips the
timer (#3541). The peak is the
most requests ever in flight at once, so on a run whose users wait in step it
can read the full user count though most of the run had far fewer in flight;
avgInFlight is the figure that measures utilisation. avgInFlight is present
for a load run stored since issue #2821, 0 included; absent for a run stored
before it, a collection (design-mode) run, and a run reported from its sampled
results, never a 0 nobody measured.
summary.setupOverhead and summary.cleanupOverhead (issue #2894) are the two
stretches of a load run outside testDuration, in seconds. setupOverhead
runs from the run's own thread taking it up to load start: reading the run's
settings, building its request or plan, and the script.setup pass (a
collection's, or a single request's lifecycleElements), so a slow setup
script shows here and never in testDuration. cleanupOverhead runs from the
end of load, the drain included in testDuration before it, to the run's
background threads (the metrics tick, the token-refresh watchdog, the monitor
scrape) having stopped, before the deferred script and schema passes and the
summary write. Both read 0 for a failed run's best-effort summary, a partial
report of a running run, a run reported from its sampled results, and a
collection (design-mode) run, none of which times them. A run stored before the
issue stored the cleanup figure under the setup name: its report carries that
figure as cleanupOverhead and has no setupOverhead, rather than a setup
time nobody measured.
sampling says how much each bounded store thinned away: all zeros means the
error, trace and tested-response sets are complete, and a non-zero count means
they are a uniform sample of the whole run (reservoir retention) rather than
a truncated prefix of it. The section is absent on a run recorded before it was
reported, which is not the same claim as "nothing was dropped". It does not
describe results[], which has its own selection rule below.
results[] is not a uniform sample (#2210). A non-scenario run returns at
most 100 stored rows. When it stored more, the rows are chosen by value: every
row with a failing status (anything outside 2xx/3xx, including the 0 of a
transport failure) takes a slot first, up to the cap, and rows that succeeded
fill the remainder in storage order. The chosen rows are listed in timestamp
order, ties broken by row id, whichever way they were selected. A Scenario
run keeps every stored step (bounded at write time by maxScenarioStoredSteps,
see stepsStored). Two top-level keys, always present, say whether the array
was cut: resultsStored is the number of rows stored for the run and
resultsCap is the cap applied (equal to resultsStored for a scenario run).
resultsStored > resultsCap is the only signal that results[] is a selection
and not the whole set; both sit beside results rather than inside sampling
because that section is optional.
responseSamplesDropped counts responses the post-run test scripts and schema
checks never saw, for either of the two bounds on that store: the count cap
(max_response_samples), and the byte budget (max_response_sample_bytes) that
drops a whole sample once the run's retained bodies would exceed it. Both mean
the same thing to a reader - this response was not validated - and neither ever
stores a cut body, because a deferred check reading one reports a failure the
target never produced. They differ in one way worth knowing: the count cap
displaces an incumbent, so the tested set stays a uniform sample of the run,
while an exhausted byte budget stops admitting - a run that spends it is graded
on the part of the run whose bodies fit. The counter cannot say which bound
applied on its own; responseSampleBudgetSpent is the answer (issue #1192).
true means the byte budget ended at least one sample, so the tested set is
drawn from the part of the run whose bodies fit; false means only the count
cap displaced anything, so the tested set stays a uniform sample of the whole
run. It is written by every run recorded since the marker existed, and is
absent on a summary written before that - absent means "not known", not
"not spent", which matters because weakening the uniform claim for every
pre-marker run would cost the accurate message in the case that is nearly all
of them: only a target whose retained bodies average more than ~256 KiB
reaches the budget at the defaults. The app's retention note drops its
uniformity sentence only when the key reads true; absent or false both
keep it.
Three of its keys are about captured responses rather than retention:
responseBodiesCaptured is how many exchanges the run stored (see
GET /runs/:runId/samples), and is also the run's own
marker that it holds response data stored verbatim - non-zero is what the
Samples tab warns on. sampleBodiesDropped counts samples whose headers were
kept but whose body was dropped once the run's maxSampleBytes budget was
spent. exemplarsDropped counts per-status exemplars refused because
max_exemplar_results was full, which only a target answering with more
distinct status codes than that limit can reach. All three are absent on runs
recorded before 0.15.0.
monitor is present only for a run that declared a
monitor block - absent is "this run
scraped nothing", never "the target reported zeros". samples counts scrapes
that read at least one requested name; the others are split by cause.
failures counts the scrapes that got no 2xx answer, and lastError, present
once one has, names the most recent one's cause: HTTP <status>, or one of
timed out, unreachable, host not found, TLS handshake failed,
proxy failed, URL refused, too many redirects, undecodable body,
response too large and transport error. It is never the transport's own
message, which can quote the URL. noMatchScrapes counts the 2xx answers that
carried none of the requested names. So samples: 0 with a non-zero failures
says the endpoint was unreachable or erroring for the whole run, and samples:
0 with a non-zero noMatchScrapes says it answered every time but the names
matched nothing. A series that never produced a reading is absent from series
for the same reason. noMatchScrapes and lastError are absent on a run
recorded by an engine that predates them, whose failures count no-matches
too. The per-sample
readings are served separately by
GET /runs/:runId/monitor.
results[].id is the results row id, and the join key against
GET /runs/:runId/samples. It is absent on reports served by an engine older
than 0.15.0. The rows are listed by timestamp, not by id.
metadata.configuration carries the load-test tuning knobs present in the
snapshot (mode, duration, concurrency, iterations, startConcurrency,
rampUpDuration, timeout, comment, followRedirects, maxRedirects -
each omitted when absent, and recording what the run was sent, never a default
the engine filled in; issue #2437) plus httpVersion, which is always present with the
same "auto"-when-unknown normalization GET /runs's summary uses (see
above), and acceptEncoding (issue #1488) and expectContinue (issue
2516), read out of the snapshot's defaultHeaders and omitted on the same¶
terms as GET /runs's summary key acceptEncoding (expectContinue is on
the report only, not in the list row: only the comparison reads it). rps in the raw snapshot is renamed to targetRps here,
and rps is read first (targetRps is the rate only when rps is absent,
null or zero), as in GET /runs's summary.
dataRowCount is the size of the data set a run bound, and dataFileName /
dataFileHash (issue #2051) the file it came from, by display name and
SHA-256 of its bytes, never its path, with dataFileCastNumbers: true (issue
2540) when that file's numbers were read as numbers. A single-request run's¶
are read off the snapshot's top level; a collection run's off its scenario
manifest, so every report of a run that named a file carries them here, and a
run that named none has no such key. carriedBudgets (issue #2195) is the list of thresholds
keys the client sent as carried over from an earlier run rather than set for
this one, echoed as sent and omitted when the run sent none (see
Carried-over budgets); GET /runs's
summary does not carry it. A capacity run's own two knobs (issue #2925),
stepDuration (the string the run was started with, as duration is) and
sloMs, are echoed as sent, on a capacity run only and omitted when it left
one at its default: the search's effective budget is the report's
capacity.sloMs. A run of any other mode has neither key, whatever its
snapshot holds. POST /export/run-report carries both in config.configuration.
GET /runs/:runId/samples¶
Get the response headers and body a load run captured for its retained samples. Paginated; no deprecated alias - the endpoint is new in 0.15.0, so there is no pre-consolidation spelling for it to keep working.
Deliberately not part of GET /runs/:runId/report. That path loads every
results row for the run and JSON-parses each trace_data to accumulate
aggregates that never look at a body, and the dashboard polls it; at 1000
samples carrying 32 KiB bodies, folding them in would turn every poll into ~32 MB
read from SQLite and parsed. So the bodies live in their own tables and are
fetched here, per page, only when a reader actually expands a sample.
Query params:
| Param | Default | Notes |
|---|---|---|
limit |
50 |
Capped at 500; a non-numeric value falls back to the default |
offset |
0 |
Floored at 0 |
What a run captures - and does not - is described under
result_bodies: every error, the slow outliers,
and the first three of each distinct status code, within maxSampleBodyBytes
per body and maxSampleBytes for the run. A uniformly sampled success carries
no body by design.
Response:
{
"data": [
{
"resultId": 41,
"response": {
"headers": { "content-type": "application/json", "server": "nginx" },
"body": "{\"error\":\"upstream timeout\"}",
"bodyEncoding": "utf8",
"bodyBytes": 28,
"contentType": "application/json"
}
},
{
"resultId": 42,
"response": {
"headers": { "content-type": "image/png" },
"bodyBytes": 20480,
"contentType": "image/png",
"binary": true
}
}
],
"pagination": { "total": 23, "limit": 50, "offset": 0, "hasMore": false, "returned": 23 }
}
resultId is the results row this exchange belongs to - join it against
results[].id on the report rather than re-deriving an order.
The response node always carries headers and bodyBytes (the size as
received, before any truncation). The rest is conditional, and each key means
something the bytes alone cannot say:
| Key | When present | Meaning |
|---|---|---|
body |
Not binary | The stored bytes, as bodyEncoding says. "" when the response had none, or when the body was dropped |
bodyEncoding |
Not binary | "utf8": body is the stored text. "base64": the stored bytes are not valid UTF-8 text (or hold a NUL) and body is their standard, padded base64 |
bodyTruncated |
true only |
body is a prefix; the response was larger than maxSampleBodyBytes. Same convention design-mode traces use |
bodyDropped |
true only |
The run's maxSampleBytes budget was spent before this sample: headers kept, body not. Distinct from an empty response body |
binary |
true only |
Stored as a descriptor - bodyBytes and contentType, no bytes. See result_bodies for why a binary body is never stored as text |
contentType |
Non-empty | The response's Content-Type |
events |
Streams only | What the stream delivered, in the trace's events shape (see below). Absent for every sample that did not stream |
bodyEncoding: "base64" is not binary: true (issue #3159). binary
is decided when the sample is captured, from the Content-Type and the first
1024 bytes, and such a body is never stored. A body that passed that sniff is
stored as text, and bodyEncoding is decided when the sample is read, over
every stored byte, because a JSON string holds only UTF-8: a NUL or a byte
that is not UTF-8 past the first 1024 lists the whole body as base64, with
bodyBytes still the size as received, never the encoded length. A body the
maxSampleBodyBytes cap cut inside a multi-byte character is first trimmed
back to a character boundary, so it stays utf8 with bodyTruncated set
rather than turning the whole prefix into base64.
A streamed sample carries its events (0.17.2). events is
{items, totalEvents, eventsTruncated} - the same node a streaming design run
stores on its trace, minus endReason: under load a stream ends by server close
or by one of two caps (maxStreamEvents / maxStreamDurationMs) and nothing
per sample records which, so no reason is named rather than one invented. The
list is parsed out of the stored body on read, bounded by sseMaxStoredEvents,
and totalEvents is the count taken on the wire - so a capture the
maxSampleBodyBytes cap cut still reports the whole stream's length, with
eventsTruncated covering both that cut and the stored-events cap. The events
are parsed from the stored bytes whatever bodyEncoding says, and a byte in
an event that is not UTF-8 is answered as U+FFFD. See
result_bodies for why the count is stored and
the list is not.
"events": {
"items": [ { "event": "token", "data": "hello", "sourceId": "42" } ],
"totalEvents": 4000,
"eventsTruncated": true
}
Captured data is stored verbatim - no redaction, consistently with
design-mode traces, which already store request headers as sent. A response
Set-Cookie is captured along with everything else. It is deleted with the run,
so maxRunsRetained is its expiry.
A run that captured nothing is an empty page, not an error; an unknown run id is a 404 in the shared error shape.
Response (404):
PUT /runs/:runId/baseline¶
Pin (or unpin) any run - design, load or scenario alike. PUT rather than
POST per the create vs update split: the
run already exists, and this updates it. There is no deprecated alias; the
endpoint is new.
Two things follow from a pin, and both are the point of it:
- Retention never expires it.
prune_runsskips a baseline under both count caps and the age cap, and a pinned run does not count towardmaxRunsRetainedormaxDesignRunsRetainedeither - a pin a cap could expire is not a pin, and pins crowding a cap would evict the recent history the cap exists to keep. - Clients can find it:
GET /runs?baseline=true&requestId=<id>&limit=1, or...&collectionId=<id>&...for a load run over a collection.
The engine's own meaning of the flag stops there - it holds no opinion about
why a run is kept. A client's vs-baseline comparison is a narrower, load-only
reading of the same flag: only a load run has the percentiles and throughput a
diff needs, so a comparison lists type=load alongside baseline=true
(GET /runs?baseline=true&type=load&requestId=<id>&limit=1) rather than
treating any pinned row as its baseline - otherwise a more-recently-pinned
design or scenario run of the same request would shadow it.
Several runs may be pinned at once (one per request or collection is the expected use). The engine records the pin and holds no opinion about which baseline applies to which run - that selection is the client's, so a pin never unpins anything else.
Request body - baseline is required and must be a boolean:
Response 200: the updated run row, in the same shape
GET /runs lists (including summary and origin, but never
resultSummary), so a client can patch its cached row instead of re-listing.
400 when the body is not JSON, has no baseline, or baseline is not a
boolean - including null. Unlike the merge-patch resource updates, an
unusable value here is refused rather than ignored: this body has exactly one
field, so ignoring it would answer 200 to a request that changed nothing.
404 when no run has that id.
DELETE /runs¶
Clear run history: delete every run - design, load and scenario alike - except the ones retention never deletes either (issue #2429):
- a run pinned as a baseline (see PUT /runs/:runId/baseline) is kept - the pin is a promise to keep the run, and a bulk clear does not break it. Unpin first, or name the run in DELETE /runs/:runId, to remove one;
- a run whose stored status is still
runningorpendingis kept and left running. Stop it, then clear again.
Each run goes with its metrics, results and captured bodies, through the same cascade and the same batched pass as retention: batches of 100, each in its own transaction, and each row re-read under that batch's lock, so a run pinned or started while the clear is under way is spared. A deleted run is gone for good; runs have no trash. The call takes no body and no query parameters.
Response 200:
deleted is the length of deletedIds, the runs this call removed, so a
client can close whatever was showing one. keptPinned counts the pinned
baselines stored once the clear finished; a run kept for being in flight is in
neither number. An empty history answers {"deleted": 0, "keptPinned": 0,
"deletedIds": []}.
DELETE /runs/:runId¶
Delete a run and all associated metrics/results.
An active run is stopped first. Deleting a run that is still executing used
to remove its rows while its worker kept writing new metrics and results against
the same id - orphan rows that no run owns, and a run that partially reappeared
as it finished. So a run that is still active is stopped exactly as
POST /runs/:runId/stop stops it, and the rows are removed only once its worker
has completed its final writes. Expect the call to take as long as the stop does
(up to ~5s for a large run).
If the worker has not settled within that window nothing is deleted and the call
returns 409 - a half-deleted run racing a live writer is worse than a delete
that has to be retried. The stop still stands, so a retry a moment later
succeeds. A run whose stored status is running but which has no worker (the
daemon restarted under it) has nobody to race and is deleted immediately.
Response:
409 Conflict (still stopping - nothing was deleted):
{
"error": {
"code": "conflict",
"message": "Run is still stopping; it was not deleted. Retry once it reports a terminal status."
}
}
Scripting¶
GET /scripting/completions¶
Get script engine API completions for UI autocomplete.
Response:
{
"version": "1.0.0",
"engine": "quickjs",
"completions": [
{
"label": "pm.test",
"kind": 1,
"insertText": "pm.test(\"${1:test name}\", function() {\n\t${2:// assertions}\n});",
"detail": "pm.test(name: string, fn: () => void)",
"documentation": "Define a test with assertions..."
}
]
}
An entry whose kind is 28 (Monaco's Snippet kind) carries two extra
members no other entry does: context, one of "pre", "test" or "both",
which script kind the template belongs in; and group, one of "Variables",
"Request", "Response", "Tests", "Signing" or "Logging", the heading
it is listed under. A client uses the pair to build a filtered, grouped
snippets picker for whichever panel - Pre-request or Tests - the author has
open, rather than offering the whole table regardless of where it would run.
Neither field is present on a non-snippet entry.
GET /scripting/types¶
The same pm.* surface as TypeScript declarations, for Monaco's TypeScript
worker. A completion list can only populate a dropdown; the declarations are
what give hover documentation over an existing call, signature help while
typing arguments, and go-to-definition within the surface.
The declarations are generated from the completion table above, not
maintained separately - a hand-written pm.d.ts in the app would be a second
declaration of a surface the engine owns, and the two would drift the first
time a method was added to one and not the other. The derivation works because
a completion entry already carries its type: a function's detail is its
signature, a field's detail is its type. See
engine/src/http/routes/script_types.cpp.
Output is deterministic - the same table always produces byte-identical text,
so a client may cache on version.
Response:
{
"version": "1.0.0",
"engine": "quickjs",
"libUri": "ts:vayu/pm.d.ts",
"typeDefinitions": "interface VayuExpectation {\n\tequal(expected: any): VayuExpectation;\n…"
}
| Field | Description |
|---|---|
libUri |
Model URI the app registers the declarations under (addExtraLib) |
typeDefinitions |
The .d.ts source |
The file also declares the names a script may reach for that the sandbox
lacks, with the reason as documentation: the host globals of a browser or
Node (fetch, URL, Buffer, ...), and the libraries Postman bundles that
the require() shelf does not carry (cheerio, Backbone), whose hover names
the replacement Postman itself gives. require,
CryptoJS, _, tv4 and xml2Json are declared as what they are, with a declare module for
each name on the require() shelf (crypto-js #2578, uuid #2650, lodash
2651, moment #2652, csv-parse/lib/sync #2653, xml2js #2654, chai #2655, ajv and tv4 #2656) and one require¶
signature keyed on those names, so a name off the shelf is a type error. Postman's postman object and its pre-pm.*
globals (tests, responseBody, responseCode, ...) are not among them: they
run (#2577), and are declared from the completion table like pm itself, each
as the value it is.
It also carries interface augmentations for standard-library members the runtime
runs but the TypeScript bundled with the editor does not declare yet
(RegExp.escape, Math.sumPrecise, JSON.rawJSON, Uint8Array.fromBase64 and
toHex, and their siblings), under their own banner; a row retires when that
TypeScript declares its members (#3485).
That is not padding: the app suppresses "Cannot find name" (2304), so a name that
is merely undeclared draws nothing. A name typed never makes the call, member
access or assignment that follows an error ("not callable", "property does not
exist"). never is assignable to everything, so a bare read passes
(console.log(cheerio)).
Declaring a name does not reserve it: the app compiles each script as a module
(moduleDetection), so a script's own const data = ... shadows the declared
data instead of redeclaring it. A test executes typeof <name> in the real
script engine for every root, so the list cannot drift from the runtime, and an
entry leaves the table in the commit that makes the runtime provide it.
The assertion chain is one interface, read by leaf rather than by path
(#1209). A completion label is a dotted spelling - to.have.deep.property is
what someone types - and not the shape of the object: create_expectation
installs to, have, deep and property on the same expectation, and every
one of them hands that expectation back. So the generator takes each label's
last segment as the member and every earlier segment as evidence that word is a
chainer, and emits a single VayuExpectation where every chain word is a
property of that type and every matcher a method returning it - chai's own
model. Read as a path tree it emitted two interfaces instead, and a matcher was
reachable only along the one route some label happened to spell, so
.to.be.a('string').and.match(/x/) was an editor error on a chain the engine
runs. Where two labels share a leaf (to.have.property,
to.have.deep.property, to.have.nested.property), the plainest spelling
declares the member and the longer ones fold their documentation into its hover
under their own labels.
The guard is set equality rather than a list of names:
TheDeclaredChainIsTheObjectTheRuntimeBuilds reads the interface's members out
of the generated text and the expectation's out of the real script engine
(Object.getOwnPropertyNames, so no terminal getter is triggered) and fails on
a member either side has alone. A matcher added to the runtime and not to the
table now reddens instead of being missing.
Two things the generated file still cannot get from the table, both handled in
script_types.cpp and guarded by script_types_test.cpp:
- Which label roots open the chain.
that.is.not.emptyis a chain andconsole.logis a global, and nothing in either entry says which; the chain roots (to,and, and chai's twelve language chains) are named in the generator, so a label rooted at one is filed under the chain rather than declaring a top-levelthatnothing binds. - Unparseable parameter lists. Two entries document an overload in prose
TypeScript cannot parse (
upsert({ key, value }) | (name, value)). Those fall back to(...args: any[]), keeping the member callable rather than emitting a file that does not compile.
The declarations are compiled, not just grepped¶
script_types_test.cpp asserts on substrings of the generated text - every
listed member appears, the chain returns the chain, an optional field keeps its
type. That cannot catch the class of defect where a declaration contains every
right name and still does not type-check, and four of those shipped (#463):
pm.cookies.jar() emitted twice with the object overload winning, every jar
method's signature emptied by the () inside its own label, pm.info.eventName
read as prose and typed void, and two pm.expect chains shorter than the
documentation beside them.
So the durable guard compiles every ```javascript block mentioning pm. in
scripting.md and
pm-api-compatibility.md against the real
declarations and requires zero errors, with the app's own compiler options and
suppressed codes. The same suite compiles scripts that use the absent names and
requires the error each should draw, and scripts that declare one themselves and
requires none. The documentation and the declarations then hold each
other up: an example the editor would squiggle fails the suite, and so does a
declaration that stops describing what the docs recommend.
It needs a TypeScript compiler, which ctest does not have, and the generator
needs the engine, which vitest cannot run. The two halves meet at one checked-in
artifact - the same shape as variable-resolution-conformance.json:
| Where | What |
|---|---|
engine/tests/fixtures/script-typedefs.d.ts |
The generated declarations, checked in |
ScriptTypesTest.TheCheckedInDeclarationsMatchTheGenerator |
Pins that file to the generator byte-for-byte, so the copy cannot drift |
app/src/hooks/script-typedefs.docs-compile.test.ts |
Compiles the docs' blocks against it |
A change to the surface therefore shows up as a diff in the declarations the editor will serve. Regenerate deliberately:
HTTP Status Codes¶
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad request (invalid JSON, missing required fields, invalid OAuth 2.0 config) |
| 401 | OAuth 2.0 provider rejected the token request |
| 404 | Resource not found |
| 409 | OAuth 2.0 interactive authorization required (/run pre-flight, /oauth2/token) |
| 412 | A whole-record PUT or a POST /globals whose If-Match no longer names the stored row (precondition_failed, Conditional updates) |
| 429 | A start refused at its cap: oauth2_authorize_limit_reached (16 unsettled sign-in attempts), mock_issuer_limit_reached (8 mock issuers) |
| 500 | Internal server error, including a storage failure that is neither a full disk nor a lock (resource writes) |
| 502 | Upstream network error (OAuth 2.0 token endpoint, /import/fetch proxy) |
| 503 | Engine is shutting down (POST /runs, see below), or the database stayed locked past its busy timeout (a resource write; carries Retry-After: 1) |
| 504 | OAuth 2.0 token endpoint did not answer within the defaultTimeout setting (/oauth2/token, oauth2_timeout) |
| 507 | The disk holding the data is full (a resource write, insufficient_storage) |
Notes¶
- All timestamps are Unix milliseconds (since epoch)
- Variable substitution uses
{{variableName}}syntax - Environment variables are resolved in order: environment → collection → global
- Load test metrics are collected every 100ms
- SSE connections timeout after 30 seconds of inactivity