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. It has CLI, Python SDK, Go SDK and REST examples, sample CLI table output showing one executing and one idle query, a representative JSON response with the same mix so the slotsHeld versus count distinction is visible in the data and not only in prose, and a field-by-field table for a query entry. The table calls out the three optional fields that are easy to misread as zeros: holdsSlot is null only when the state is unknown, hasMorePages is absent until a page has completed and absent means "not yet determined" rather than "no more pages", and batchesInScope of 0 means the scope estimate was unavailable so progress cannot be computed, not that no work has been done.

Reading Your Limits Directly covers the limits endpoint, with the same four tabs, a representative response and a field-by-field table covering every field in that response. 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. Because there is no CLI cancel command, that entry carries a concrete DELETE /v1/search/{queryId} example at the point of use and states plainly that cancelling is available through the REST API only, so the recovery path does not end at a step the reader cannot perform.

Both endpoints note the insight.evt.get permission they require and link to the API Keys page, and both REST tabs use the $SEARCH_HOST / $LC_JWT convention established on the Query Console page rather than re-deriving the search host inline.

Go snippet module pin points at an unreleased SDK revision

snippets/golang/go.mod is moved from v0.0.0-20260706232626-4212dfffc585 to v0.0.0-20260726172822-e1078d02bc52. That newer pseudo-version is the commit on the Go SDK branch that adds GetSearchLimits / ListOpenQueries / ListAllOpenQueries; it is not a tagged release. The snippet build (go build ./... + go vet ./...) passes against it today, but this pin must be moved to a tagged release before this PR merges, otherwise the documentation's snippet build depends on an unmerged branch revision that can disappear.

The Python side has no equivalent problem: the Python snippet job only byte-compiles with py_compile and verifies that the limacharlie.sdk.search import path resolves, neither of which touches the new methods, so the Python snippets are safe against the currently pinned limacharlie==5.5.1.

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 documentation page, docs/4-data-queries/query-limits-and-performance.md. Additive: two new sections and one new troubleshooting entry, plus edits to an existing troubleshooting bullet. No existing section is rewritten or removed, and no other page changes.

Four new compiled snippets are added and included with --8<-- so CI type-checks the SDK examples against the published SDKs instead of letting hand-written inline code drift:

• snippets/python/search_limits.py
• snippets/python/open_queries.py
• snippets/golang/search_limits/main.go
• snippets/golang/open_queries/main.go

The Go limits snippet deliberately demonstrates the nil-versus-zero handling on the execution limits, since that is the contract a Go caller can silently get wrong: those fields are *int64 and nil means "not enforced".

Verification

• cd snippets/golang && go build ./... && go vet ./... passes with the bumped pin (and with GOFLAGS=-mod=readonly, as CI runs it).
• python3 -m py_compile snippets/python/search_limits.py snippets/python/open_queries.py passes.
• mkdocs build --strict passes, and the rendered page contains the snippet bodies, so every --8<-- path resolves.
• npx markdownlint-cli2 reports 0 issues, and scripts/check-list-numbering.py reports 0 new numbering breaks.

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, and the source of the go.mod pin bump above

🤖 Generated with Claude Code