Guides

# Querying with jq

Return only part of a bin with a jq filter.

Add `query` with a [jq](https://jqlang.org/) filter to any read, and the response is the filter's result instead of the whole document.

terminal

```
curl "https://api.hotcfg.run/v1/acme/mobile-flags?query=.features.checkout_v2"
# true

hotcfg get mobile-flags --query '.features'
```

A filter that returns several results returns them as a JSON array.

To merge overrides for one platform, build number or rollout bucket into your flags, see [version targeting](https://hotcfg.run/docs/recipes/version-targeting).

## Limits

| Limit | Value |
| --- | --- |
| Filter length | 512 bytes |
| Run time | 50 ms |
| Result size | 2 MiB |

An invalid, slow or oversized filter answers `422` with a `query_*` code. A filter with no output (`empty`, or a `select` that matches nothing) answers `422 query_empty`, so an app never mistakes it for config; end filters with `// {}` to always return a value.

On a public bin, each distinct filter is cached at the edge like the plain URL: for an hour, purged on every publish, and served for up to a week if our servers are down. The first read of a new filter in each Cloudflare data center reaches our servers.

Last updated 10 November 2026
