docs(queries): document how to see what is using a concurrency limit, and how to read the limits themselves

[tomaz-lc]

Details

The query-limits page stated the concurrent-query limit and what happens when it is reached, but not how to find out what is consuming it, nor how to learn what the limits actually are for a given organization. Both are now answerable through the API, so this documents them.

Adds two sections and one troubleshooting entry.

Seeing What Is Using Your Limit covers the distinction the open-query listing exists to make: the searches an organization has open and the subset consuming its limit are different numbers, because a paginated query between pages is open and resumable but holds no slot. Includes the per-entry fields, how to cancel a query to free its slot, and the caveat that progress advances at page boundaries - so a query that returns everything in one response, notably any aggregation, reports 0% for its whole life and then leaves the listing.

Reading Your Limits Directly covers the limits endpoint, with CLI, Python, Go and REST examples, a representative response and a field-by-field table. The framing is "ask rather than discover": every limit on the page was previously learnable only by hitting it.

A paginated query cannot be resumed is a new troubleshooting entry. The resumable window is measured from when the query was submitted, not from its last page, so one left paused long enough expires even though it was producing pages recently. That is the non-obvious part and the likely cause. It also distinguishes that window from page retention, where re-reading an aged-out page recomputes it and shows up as a slow page rather than a broken one.

The existing rate-limit troubleshooting entry now points at the limits endpoint for confirming what the cap actually is, before investigating what is holding it.

Conventions a reader has to know, stated in both new sections

A limit that is not enforced is reported as null, not 0 - in a document of limits a zero would read as "nothing allowed". An unrecognised field means "not applicable to this deployment" rather than zero, since the response is additive and gains fields over time.

Blast radius / isolation

One page, docs/4-data-queries/query-limits-and-performance.md. Additive: two new sections and one new troubleshooting entry, plus one sentence added to an existing troubleshooting bullet. No existing section is rewritten or removed, and no other page changes.

No compiled snippets are added, so the snippet-test build is unaffected. The Python and Go examples are illustrative and deliberately kept out of the compiled snippet tree until both SDKs have released versions carrying these methods.

Notable contracts / APIs

Documents existing API responses; nothing here defines or changes a contract. Both endpoints are gated server-side, so the text avoids implying either is universally available - the limits response carries capabilities.openQueryListing for exactly that reason, and the page explains it.

Related PRs

• python-limacharlie#327 - the SDK and CLI support the examples use
• go-limacharlie#260 - the Go SDK support the examples use

🤖 Generated with Claude Code