Retool additionalScope: The Right Way to Pass Parameters to Queries

Let me guess, you're probably trying to pass a value — maybe a user ID, status, or form input — into a Retool query. You have already tried something like {{ someVar }} but it's not working in a .trigger() call. That's exactly where I was, until I discovered additionalScope.

In this post, I’ll show you how to pass parameters properly when triggering queries in Retool — and how additionalScope it can help you.

🧠 What Is additionalScope in Retool?

If you are familiar with basic programming, it’s just like your normal passing parameters to function when you call it. If you come from a non-tech background, it’s just like ordering a custom t-shirt online. You don't just click "make shirt" - you specify size, color, design, and text. The printing service (function) takes all your specifications (parameters) and creates your unique product.

🚀 Let’s dive into a working example.

Let’s create a hypothetical scenario. Let’s say we have a form with an input field named Name, with the regular submit button. Now we want to manually trigger a JS query, but here is a twist, we want to pass a random number with that for some odd reason, let’s say grading ( BTW that would be unfair), when the user presses the submit button. How can we do that?

First, let’s quickly set up this app.

⏭️ Next Steps

1. We want to somehow run this query1 query when a user presses the submit button.
2. Somehow, we have to pass name and marks to this query, so query 1 can output it.

Let’s connect the submit button to this query so pressing the button somehow runs this query. Here’s how we can do that.

Let’s pass the name and marks to this query when we run it? I’ll share 2 ways to do so.

1. 🎛️ First Method: Using Control Query

We’ll add the required variable names in the query in the query’s additionalScope section ( name & marks in this case. This will allow us to pass those parameters from the place we call it.

Let’s now run and see the output in the debug console.

2. ✍️ Second Method: Using Run Script

We can change the event handler we attached to the submit handler to use Run Script instead of control query We did earlier, and paste in the following snippet, which is another way of doing the same thing.

query1.trigger( { additionalScope : { name : textInput1.value, marks : Math.random() } } )

Note: query1 is the name of the query we are trying to trigger/run, name and marks are the parameters we want to pass to query1 when we force it to execute?

🔍 Can We See the Parameters Passed to a Retool JS Query When Triggered?

Yep, once the query runs, we can expand it in the debug console to see exactly what parameters were passed in.

🏁 Wrapping Up

Passing parameters into queries in Retool doesn’t have to be messy, and additionalScope is a seriously underrated feature that makes your struggle disappear.

Whether you're dealing with row actions, dynamic modals, or looped query executions, this technique lets you pass exactly what you need — nothing more, nothing less — at the moment you trigger your query.