API filtering is now generally available

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:

• Find specific resources without paging through everything
• Reduce API calls and response sizes
• Simplify your integration code

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.

How it works

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")

It’s just CEL

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:

• Combine logical conditions with && (and), || (or), and ! (not) operators
• Comparative operators <, <=, ==, !=, >=. >
• Substring checks such as startsWith(), contains(), and endsWith()
• Length and emptiness checks with size(), == ””, and == null

See the full list of supported operators.

Get started

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.