URL query parameters

Retool's built-in URL query parameters allow you to control certain characteristics of an app when launched. You can also configure your own URL query parameters and deep link to specific sections or data.

Built-in URL query parameters

You can launch an app and include any of the following parameters to alter its state when launched, such as loading a previous release or using a specific environment. Use the following URL format when including query parameters:

https://[organization].retool.com/apps/[app]?[parameter]=[value]

Parameter	Value	Description
`_historyOffset`	Any integer (`1`, `2`, `3`, etc.)	Opens the Retool app to a previous point in its save history, counting back from the latest state. This is useful if you need to roll back changes because an app is not in a functional state (e.g., an infinite loop). If you edit an app while in an offset version, those changes are saved at the "newest" position in the app history. We recommend using releases as you make changes to apps.
`_embed`	`true` or `false`.	Hides all non-app UI. Useful for embedding Retool into other applications.
`_releaseVersion`	Any valid release number (e.g, `2.1.1`) or `latest`.	Opens the Retool app to a specific release version. Helpful for testing or sharing new changes with teammates.
`_environment`	Any valid environment name (e.g., `production` or `staging`).	Opens the Retool app with the corresponding environment credentials. This is the same as clicking the environments dropdown via the UI.

📘
You can also define custom query parameters that can be used in queries and link directly to records.

Custom URL query parameters

You can specify your own URL query parameters to include custom values, allowing you to effectively sync its state to the URL. This makes it possible to link directly to specific records.

For example, let's say you've built an app that allows you to search for users and their purchases. You've selected a user and you want to share that selection with a coworker.

User and purchase selected

With deep links, you can copy and paste the URL and send it to your coworker. Without deep links, you'd need to send a link to the app and explain to your coworker what to search for.

To use deep links:

Bring up the URL Parameters editor by opening up the file menu and clicking on URL parameters:

We want the page to automatically update the URL whenever a user searches for a value, selects a user, or selects a purchase. To do that, we'll configure the parameters:

Storing page state in the URL.

Now, the page will have a URL that looks like this: https://yourdomain.tryretool.com/presentation/UsersDashboard#customerId=45&purchaseId=1979&searchTerm=ja

One-way syncing is now working (when page state changes the URL changes too), but we also want to sync the other way. If you open the app with these parameters, we should set the search box, and the selected rows in the tables correctly. To do that, we'll fill in the 2nd half:

Reading page state from the URL.

Now, when you open up the URL https://yourdomain.tryretool.com/presentation/UsersDashboard#customerId=45&purchaseId=1979&searchTerm=ja, you'll see the correct selected customer and purchase.