query

Search and filter findings. Returns structured results.

Supports lookup by ID via id= (single) or ids= (batch). Missing IDs are silently absent from the result so the caller can diff. For a strict single-ID fetch that errors on miss, use get instead.

Args:

• id: Fetch a single finding by exact ID (e.g. CB-1383)

• ids: Fetch multiple findings by ID list; missing IDs are skipped

• status: Filter by status (open, in_progress, fixed, not_a_bug, wont_fix, stale, deferred). Aliases accepted. Use 'deferred' to find items with active blockers.

• severity: Filter by severity (critical, high, medium, low)

• category: Filter by exact category

• file: Filter by file path (substring match)

• source: Filter by source (claude, ruff, human, etc.). Compares the FIRST reporter — the column is frozen at first report (BT-4); later observations' sources live only in the occurrence ring (meta.occurrences[*].source), and an imported observation's ring source can be a peer tracker's.

• tag: Filter by tag (finds findings containing this tag)

• meta_key: Filter by metadata key existence. Reads the row's AUTHORED top-level meta (the column), never the occurrence ring.

• meta_value: Filter by metadata value (requires meta_key; same authored top-level meta as meta_key — ring meta is not consulted)

• commit: Matches the first-report column OR any occurrence in the ring (prefix match, hex validated) — "what was observed on this commit" (CB-128). staleness_check uses the NEWEST ring entry instead: a different question.

• ref: Filter by reported_at_ref (exact match, never prefix) — matches the first-observed or manually assigned release ref (BT-4); per-occurrence refs in the ring are not consulted.

• fingerprint: Filter by identity fingerprint (exact match)

• group_by: Group results by: severity, category, status, file, source, tag, meta: (source groups count FIRST reporters — the column is frozen at first report). tag and meta:<key> do NOT partition the population: a card with two tags is counted under both, and a card carrying no value on the axis is in no group at all. The response therefore always carries population, ungrouped_rows, multi_group_rows and nonscalar_value_rows beside groups; the counts sum to the population only while the last three are 0. meta:<key> reads the AUTHORED top-level meta, like meta_key does, and a key holding ., [, ] or " is REFUSED — SQLite cannot tell such a name from a path (CB-167). A key that is absent, JSON null, or holds an object/array is ungrouped rather than invented. OVERLAPS grouping_tags DELIBERATELY and differently: that tool is a tag census with pair co-occurrence over status/category only; this is a distribution that composes with every filter on this tool.

• limit: Max results. A limit you PASS is always honoured: 0 means NO results, and it means that with id/ids too (CB-158 — an id list used to raise any smaller limit to fit itself, so limit=0 came back full). A negative value is an error (it used to mean "no limit"). Omit it and the page size is 100, widened to fit an ids list so a batch lookup returns every id it asked for.

• offset: Pagination offset

• resolve_anchors: Resolve each result's location anchor against the repository HEAD, so a card whose code moved reports its new path. OFF by default because it costs 2-4 git calls per ANCHORED row and this is the primary read path; the cheap half — whether a card carries an anchor at all, and the refusal token when capture found nothing to grab — is in every result either way. get resolves one card by default.