# Common URL Parameters

<br>

Multiple endpoints are available for retrieving folders and scripts, and their responses can contain substantial amounts of data. To help clients request only the information they need, these endpoints support a common set of URL parameters.

If not supplied in requests, default values for these parameters will be assumed. Note that the defaults used vary depending on whether the request is for a single script object or a folder of several script objects.

<br>

---
**subfolders** *(enum)*
<br>

Controls whether the nested contents of a retrieved folder should also be retrieved.  
Only applicable to endpoints retrieving folder items.

- `none` – the contents of any subfolders in the target folder are not included
- `all` - *(default)* – the contents, and recursively nested contents, of a retrieved folder are included

<br>

---
**scripts** *(enum)*
<br>

Controls how much of the script meta data to include (e.g., description, report comments, creation date).

- `terse` *(default for folder endpoints)* – only includes the script’s name and ID  
- `full` *(default for script endpoints)* – adds all the basic information about the script, including description, creation date, report comments, and whether the script is archived.

This parameter does **not** affect inclusion of tests, fields, runs, or results.

<br>

---
**tests** *(enum)*
<br>

Controls whether or not (and in which format) the tests of a script are included in the `tests` field of script objects.

- `none` *(default for folder endpoints)* – excludes the `tests` field entirely  
- `full` *(default for script endpoints)* – includes tests as a list of objects with fields: `id`, `indent`, `text`, and `tags`  
- `list` – includes tests as a list of strings, with leading whitespace to show indentation  
- `text` – includes tests as a single string, with each test separated by newlines and indentation preserved

<br>

---
**testswith** *(list of enum)*
<br>

Modifies how tests are returned when `tests` are included.
Most useful when formatting tests as lists or long strings.

Combine multiple values with commas (e.g., `testswith=hashtags,ids`).

- `none` *(default)* – test text is included as is, without decoration
- `hashtags` – includes tags as Twitter-style hashtags appended to each test text string. If tests are being returned as objects, the `tags` field is omitted.
- `ids` – prefixes each test text string with the test ID. Ignored if tests are objects.  
- `_ids` – same as `ids`, but right-aligns ID numbers (4 digits wide). Ignored if tests are objects.

<br>

---
**fields** *(enum)*
<br>

Controls the contents of the `fields` field of script objects.

This field defines the set of headers available for each run header (e.g., run number, tag filters, custom fields etc).

- `none` *(default for folder endpoints)* – field information is not returned  
- `full` *(default for script endpoints)* – fields are defined as a list of objects with:  
  - `id`  
  - `label`  
  - `shown` (boolean)  
- `list` – fields are returned as a simple list of all labels in use  
- `list_shown` – same as `list`, but only includes fields marked as *shown*

<br>

---
**runs** *(enum)*
<br>

Controls how test run data is included in the `runs` field of script objects.

- `none` *(default for folder endpoints)* – data on the test runs are not included
- `full` *(default for script endpoints)* – script objects will contain full run definitions, including state, tester, and header values, but not results (which depend on the `results` parameter below)
- `terse` – returns a brief summary of each test run (one-line string label summarizing header values and run number)  

<br>

---
**retests** *(enum)*
<br>

Controls whether to include old (superseded) test runs.

- **`latest`** *(default)* – only the latest retest of each run is returned  
- **`all`** – includes all test run data, including superseded runs

<br>

---
**results** *(enum)*
<br>

Controls whether results data is included in the response (but only if the `runs` field is being included).

Results are included as the `results` field inside run objects (nested in `runs`).

- `none` *(default for folder endpoints)* – the `results` field is excluded from run objects
- `full` *(default for script endpoints)* – results are included as a list of result objects, with fields:  
  - `result` *(e.g., `pass`, `fail`, `query`, `blocked`)*  
  - `comments` - string
  - `issues` - string

Only non-empty result objects are included.

<br>

---
**progress** *(enum)*
<br>

            "total": 4,
            "pass": 1,
            "fail": 3,
            "block": 0,
            "query": 0,

Controls how progress statistics are included in the `progress` field of folders, scripts, and runs.

- `none` *(default for folder endpoints)* – `progress` fields are excluded
- `terse` *(default for script endpoints)* – `progress` fields are included and contain:
  - `total` - integer - the number of tests that have a result value recorded, i.e. the total tried so far
  - `pass` - integer - the count of results marked as pass
  - `fail` - integer - the count of results marked as fail
  - `block` - integer - the count of results marked as blocked
  - `query` - integer - the count of results marked as queried
  - `summary`: a human-readable summary string of these counts
- `full` – returns progress as an object with individual count fields as well as percentage values. The percentage values are rounded to the nearest integer, set to be at least 1% if >0, and adjusted to all sum to 100% (thus making them useful for e.g. CSS %width values in a dashboard display).

<br>