Until today, finding an object in the ngrok API meant paging through the entire list resource and filtering the results client-side. This doesn’t scale well when you only care about a small subset (or just one!) of thousands of objects.
You can now filter list resources server-side using a filter parameter and get back only the objects you’re looking for. API filtering helps you:
The filter language is simple, powerful, and standardized so that you can combine conditions and build queries that match your exact needs, all evaluated server-side.
Every ngrok API list resource now supports a filter parameter where you can specify a predicate expression to select the objects you want. For example, to find cloud endpoints created in the last week, you’d query the /endpoints API resource with this filter expression:
obj.type == "cloud" && obj.created_at > timestamp(time.now).subtract("7d")
Don’t worry, we didn’t invent a new query language to learn. It’s just CEL, the Common Expression Language which is the exact same expression language used in our Traffic Policy rules.
Because it’s CEL, you get a tremendous amount of flexibility, including:
&& (and), || (or), and ! (not) operators<, <=, ==, !=, >=. >startsWith(), contains(), and endsWith()size(), == ””, and == nullSee the full list of supported operators.
Read the docs: https://ngrok.com/docs/api/api-filtering
The documentation includes details on which fields are available for filtering on each API list resource; we’ve also included a handful of usage examples to help you get started.
As always, we’d love to hear what you build and where filtering helps (or gets in the way). Drop feedback in our GitHub Community Feedback repo or reach out directly to our support team.