Skip to main content
POST
Count the sections in a scope

Authorizations

Authorization
string
header
required

API key issued from the developer dashboard. Pass as Authorization: Bearer vq_key_... (preferred).

Headers

Idempotency-Key
string | null

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.

Required string length: 16 - 255
Pattern: ^[\x21-\x7e]+$
Example:

"3f9c2a1e-7b44-4d0a-9c1e-5a6b7c8d9e0f"

Body

application/json

Section count for a scope, or for a Boolean expression within it. See POST /us/statutes/count.

A natural-language query is still refused: ranking runs over a bounded window, so "how many sections match this question" has no honest answer beyond the window size. A Boolean expression is different: membership is a yes or no per section, and the candidate index counts it (matchType: "boolean", the same expression /search would page through).

query
string | null

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.

Required string length: 2 - 500
Example:

"retaliat! /s whistleblow!"

matchType
string | null

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

Allowed value: "boolean"
Example:

"boolean"

corpusType

A public corpusType token.

Available options:
USC,
CFR,
STATE,
CONSTITUTION,
FEDERAL_RULES,
FEDERAL_LOCAL_RULES,
STATE_CONSTITUTION,
STATE_RULES,
EXECUTIVE_ACTION,
REGULATION,
FEDERAL_REGISTER,
FEDERAL_REGISTER_NOTICE,
AGENCY_GUIDANCE,
SENTENCING_GUIDELINES,
US_TAX_TREATY,
US_TREATY,
STATE_AGENCY_GUIDANCE,
STATE_AG_OPINION,
STATE_REGISTER,
SESSION_LAW,
STATUTE_COMPILATION,
AGENCY_ADJUDICATION,
CFR_ANNUAL,
USC_ANNUAL,
FEDERAL_BILL,
FEDERAL_RULES_ANNUAL,
FEDERAL_RULES_PROPOSED
Example:

"REGULATION"

state

Two-letter jurisdiction code or federal, single or list.

Available options:
federal,
al,
ak,
as,
az,
ar,
ca,
co,
ct,
de,
dc,
fl,
ga,
gu,
hi,
id,
il,
in,
ia,
ks,
ky,
la,
me,
md,
ma,
mi,
mn,
ms,
mo,
mt,
ne,
nv,
nh,
nj,
nm,
ny,
nc,
nd,
mp,
oh,
ok,
or,
pa,
pr,
ri,
sc,
sd,
tn,
tx,
ut,
vt,
vi,
va,
wa,
wv,
wi,
wy
Example:

"tx"

code

State code identifier, e.g. tx_26. With corpusType=FEDERAL_RULES, a rule set instead (frcp, uscapp_t28a_fre). Same values and checks as code on /search.

Example:

"tx_26"

article

Article label (Amendment XIV) on CONSTITUTION / STATE_CONSTITUTION, or article number (2-A) on a STATE / REGULATION code divided by article. Same values and pairing rules as article on /search.

Example:

"Amendment XIV"

titleNumber
integer | null

USC or CFR title number.

Required range: x >= 1
Example:

42

chapter

Chapter identifier. Pair with titleNumber or code.

Example:

"554"

part

CFR part identifier. Pair with titleNumber.

Example:

"240"

actStatus

Count only sections carrying this status.

Available options:
abolished,
deleted,
expired,
in_force,
inactive,
non_precedential,
not_funded,
not_yet_effective,
omitted,
proposed,
recodified,
recompiled,
rejected,
relocated,
removed,
renumbered,
repealed,
rescinded,
reserved,
revoked,
superseded,
terminated,
transferred,
unconstitutional,
vacant,
vacated,
vetoed,
withdrawn
Example:

"repealed"

excludeRepealed
boolean
default:false

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:

true

Response

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

Response for POST /us/statutes/count.

count
integer
default:0

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

Example:

43638

isExact
boolean
default:true

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.

Example:

true

parsedQuery
string | null

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

Example:

"retaliat! /s whistleblow!"

scope
Scope · object

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.

Example:
processingTimeMs
number
default:0

Server-side time for this request in milliseconds.

Example:

85.2

creditsConsumed
number
default:0

Credits actually charged for this call.

Example:

1