> ## Documentation Index
> Fetch the complete documentation index at: https://docs.requestly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# rq.execution (Execution control)

> Reference for the rq.execution namespace in Requestly scripts: read where a request sits, skip it, control collection-run order, and run another saved request.

The `rq.execution` namespace gives your scripts control over how a request runs: where it sits in your collection, whether to skip it, which request the collection runner goes to next, and how to run another saved request on demand.

## rq.execution.location

A read-only array describing where the current request sits. The array lists the path from the top of your collection down to the request itself: `[collection, ...folders, request]`. The last element is always the request's own name.

`rq.execution.location.current` returns the name of the current request (the last element of the array).

Available in both pre-request and post-response scripts.

**Example:**

```jsx theme={null}
console.log("Full path:", rq.execution.location.join(" / "));
console.log("Current request:", rq.execution.location.current);

// Example output for a request named "Get user" inside a "Users" folder:
//   Full path: My API / Users / Get user
//   Current request: Get user
```

<Note>
  The full folder path is available when a request runs inside a collection (for example during a collection run). In some contexts the array contains only the request name. Always check `rq.execution.location.length` before reading a specific level.
</Note>

## rq.execution.skipRequest()

Skips the current request. Call it from a **pre-request script** to stop the request from being sent. Everything after the `skipRequest()` call in that pre-request script is also skipped.

Use it to conditionally bypass a request, for example when a required variable is missing.

**Parameters:** none.

**Example:**

```jsx theme={null}
// Pre-request script
if (!rq.environment.get("authToken")) {
    console.log("No auth token, skipping this request.");
    rq.execution.skipRequest();
}

// Code here does not run if skipRequest() was called.
console.log("This line is skipped when there is no token.");
```

<Warning>
  `rq.execution.skipRequest()` is available in pre-request scripts only. It does not exist in post-response scripts, because the request has already been sent by then. Calling it from a post-response script throws an error.
</Warning>

## rq.execution.setNextRequest(nameOrNull)

Tells the **collection runner** which request to run next. This only has an effect during a collection run; it is ignored when you send a single request on its own.

**Parameters:**

* `nameOrNull` (string or null): The name of the request to run next, or `null` to stop the run.

It supports three behaviors:

* **Jump to a request:** pass the name of another request in the run. The runner continues from that request.
* **Repeat the current request:** pass the current request's own name to run it again. (Requestly guards against an endless loop.)
* **Stop the run:** pass `null` to end the current run. If the run uses a data file, the current iteration ends and the next data row still runs.

**Example:**

```jsx theme={null}
// Post-response script
const data = rq.response.json();

if (data.status === "pending") {
    // Poll again by re-running this request
    rq.execution.setNextRequest(rq.execution.location.current);
} else if (data.status === "error") {
    // Abort the rest of the run
    rq.execution.setNextRequest(null);
} else {
    // Continue with a specific follow-up request
    rq.execution.setNextRequest("Fetch report");
}
```

<Note>
  If you name a request that is not part of the current run, the run stops and reports an error. Use the exact request name as it appears in your collection.
</Note>

## rq.execution.runRequest(id, opts?)

Runs another saved request from inside your script and returns its response. Use it to reuse a saved login request, fetch a dependency, or chain a saved call without leaving the current request.

**Parameters:**

* `id` (string, required): The target request's ID. This is the request's saved ID, not its name. See [Getting a request ID](#getting-a-request-id).
* `opts` (object, optional): `{ variables }`, where `variables` is an object of name/value pairs applied to the request being run. Use it to override variables for that run only.

**Returns:** a `Promise` that resolves to a response object with the same shape as [rq.sendRequest](/api-client/rq-api-reference/rq-send-request#response): `code`, `status`, `headers`, `responseTime`, `json()`, and `text()`.

**Example:**

```jsx theme={null}
// Pre-request script: run a saved "Login" request, then use its token
const res = await rq.execution.runRequest("req_01H8XK2P3Q", {
    variables: { username: "ada" },
});

const token = res.json().accessToken;
rq.environment.set("authToken", token);
```

### Getting a request ID

`runRequest` needs the saved ID of the request you want to run, not its name. There are two ways to get it.

**Copy it from the UI:**

1. Open the request you want to run.
2. In the request header, next to **Get client code**, select **Copy request ID**.
3. Paste the copied ID into your `runRequest` call.

**Read it in a script with `rq.info.requestId`:**

[`rq.info.requestId`](/api-client/rq-api-reference/rq-info) returns the saved ID of the request the script is running in. This is the same ID that `runRequest` accepts, so you can capture it in one request and run that request from another. Store it in a variable that outlives the script, such as a global or collection variable.

```jsx theme={null}
// In the request you want to run later, capture its own ID once.
// (For example, in its pre-request script.)
rq.globals.set("loginRequestId", rq.info.requestId);
```

```jsx theme={null}
// In another request, read the saved ID and run it.
const loginId = rq.globals.get("loginRequestId");
const res = await rq.execution.runRequest(loginId);
rq.environment.set("authToken", res.json().token);
```

<Note>
  `runRequest` is run-scoped: during a collection run, the request you run must be part of that same run. Make sure both requests run in the same collection run, or run the target request on its own.
</Note>

### Things to know

* **The returned response is read-only data.** Variables that the other request sets do not flow back into your current script. Read what you need from the returned response and set your own variables.
* **Run-scoped during a collection run.** When used inside a collection run, the request you run must be part of that same run.
* **No nesting.** A request started with `runRequest` cannot itself call `runRequest`.
* **Up to 10 `runRequest` calls per script.**
* An HTTP error status such as `404` or `500` is not treated as a failure. Inspect `res.code`.

## Common Use Cases

### Skip a request when a precondition is not met

```jsx theme={null}
// Pre-request script
const userId = rq.environment.get("userId");
if (!userId) {
    rq.execution.skipRequest();
}
```

### Poll until a job completes

```jsx theme={null}
// Post-response script
const job = rq.response.json();
if (job.state !== "done") {
    rq.execution.setNextRequest(rq.execution.location.current);
}
```

### Authenticate by running a saved login request

```jsx theme={null}
// Pre-request script
const res = await rq.execution.runRequest("req_01H8XK2P3Q");
rq.environment.set("authToken", res.json().token);
```

## Related Documentation

* [Pre-request & Post-response Scripts](/api-client/scripts)
* [Scripts Reference Overview](/api-client/rq-api-reference/overview)
* [rq.sendRequest Object](/api-client/rq-api-reference/rq-send-request)
* [rq.request Object](/api-client/rq-api-reference/rq-request)
* [rq.response Object](/api-client/rq-api-reference/rq-response)
* [Collection Runner](/api-client/collection-runner)