US Statutes

Count the sections in a scope

Changed on Nov 7, 2026

How many sections sit in a jurisdiction, corpus, code, title, chapter, part, article or federal rule set. The scoping filters (code, article, chapter, part) take the same values and pairing rules as on /us/statutes/search.

Cost: 1 credit. A scope that matches nothing is refunded, because an empty answer here is usually a wrong filter rather than a finding.

Use it to size a job before you run it. Walking a container with /us/statutes/divisions and hydrating what you find is cheap per call and adds up across a whole corpus, so this is the call that tells you what you are about to spend before you spend it.

A natural-language query is refused, on purpose. Search ranks it over a bounded window, so "how many sections match this question" has no answer beyond the size of that window. Without a query this counts a SCOPE, which is exact. Pair the two: count the scope here, enumerate it with /us/statutes/divisions, then rank within it using /us/statutes/search.

Boolean counts. With matchType: "boolean" and a terms-and-connectors query (the syntax of /us/statutes/search), this counts the sections that satisfy the expression within the scope, the same figure a Boolean search reports as totalMatches. isExact: false marks an upper bound: the expression uses an operator the index cannot judge exactly (phrases, /s, /p, proximity, atleastN, wildcards inside proximity) or a filter it does not apply (anything beyond corpusType, state, actStatus and excludeRepealed). Same price; a malformed expression is a 422 and is not charged.

The figure counts SECTIONS. Long sections are stored as several passages and are counted once.

What an unscoped count leaves out. With no corpusType, past editions (annual CFR printings) and proposals (bills) are not counted, exactly as in /us/statutes/search and /us/statutes/coverage; the echo lists them under excludedCategories. Name one in corpusType to count it.

Agreement with /us/statutes/divisions. The browse counts distinct sections, so a section re-ingested additively (a superseded and a current copy under one id) is one section there. A scope of up to 4,000 sections is counted the same way (scope.countBasis is distinctActIds), so the children's sectionCount values sum to this figure. A larger scope reports countBasis: "sectionPoints" with scope.supersededSectionPoints, the most such copies could overstate the figure by.

post/api/v1/us/statutes/count

Request

Base URL
https://api.vaquill.ai
Auth
- HTTP bearer
- or API key in header X-API-Key
TypeScript
https://skmtc.dev/vaquill/apis/vaquill-developer-api/docs/api/v1/us/statutes/count/post.ts
A function with typed inputs. Its response is checked against the schema.

Headers

Idempotency-Keystring nullable

Optional. 16 to 255 visible ASCII characters (a UUIDv4 works). Repeating the same request with the same key replays the original 2xx response for 24 hours without charging again. The same key on a different request is rejected. With the account's cacheQueryDerivedData retention setting off, no body is stored and a retry answers 409 idempotency_replay_unavailable, still without a second charge.

Example:3f9c2a1e-7b44-4d0a-9c1e-5a6b7c8d9e0f

Request body

querystring nullable

A Boolean expression to count, with matchType: "boolean" (same syntax as /us/statutes/search). Omit to count the whole scope. A natural-language query cannot be counted: rank it with /us/statutes/search.

matchType'boolean' nullable

"boolean" to count the sections satisfying query. Required with query.

titleNumberinteger nullable

USC or CFR title number.

excludeRepealedboolean

Exclude sections whose status is affirmatively dead. A section with no recorded status is KEPT, because a missing status is not evidence of repeal. The US Code is served from a stored annual edition, so a section repealed after it closed is counted here; see the same field on /search for the measurement.

Example request

{
  "query": "retaliat! /s whistleblow!",
  "matchType": "boolean",
  "titleNumber": 42,
  "excludeRepealed": true
}

Response

The number of sections in scope, and the scope that produced it.

countinteger

Sections in scope. This is a SECTION count, not a passage count: long sections are stored as several passages and are counted once.

isExactboolean

True when the figure is an exact count. Always true for a scope. For a matchType: "boolean" count, false means count is an UPPER BOUND: the expression uses an operator the index cannot judge exactly (phrases, /s, /p, proximity, atleastN, wildcards inside proximity) or a filter it does not apply (anything beyond corpusType, state, actStatus and excludeRepealed). The same expression on /us/statutes/search reports a totalMatches that is never larger: when isExact is false the search judges every candidate over the section's full text (phrases, proximity, /s, /p) and drops the ones the index could not rule out, so the count is the bound and totalMatches is the answer. They are equal when isExact is true.

parsedQuerystring nullable

Present only for a matchType: "boolean" count: the expression as it was read.

scopeobject

The filters that produced this figure, echoed back. A count with no scope attached is not reproducible, and an ignored filter would otherwise be invisible.

processingTimeMsnumber

Server-side time for this request in milliseconds.

creditsConsumednumber

Credits actually charged for this call.

Example response

{
  "count": 43638,
  "isExact": true,
  "parsedQuery": "retaliat! /s whistleblow!",
  "scope": {
    "corpusType": "REGULATION",
    "state": "tx"
  },
  "processingTimeMs": 85.2,
  "creditsConsumed": 1
}

Changes

Nov 7, 2026340c0d24d0b6 Revision changes
- info
  added the non-success response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status

Operation history