Search US statutes, constitutions, court rules, and executive actions

Search query in natural language.

Only return sections dated in or after this year. Combine with yearTo for a window. A section matches on the first of three years it carries: the most recent amendment the publisher credits in its own history note; else its effective year, for a section adopted once and never amended; else, for corpora dated by publication rather than amendment (Federal Register proposed rules, agency guidance, adjudications, the treaty record), the document's own publication or issue year. Every one of those tracks the LAW or the document, never when we last rebuilt the corpus. A section carrying none of the three is excluded once either bound is set, so an unbounded search returns strictly more.

Only return sections dated in or before this year, on the same three years yearFrom describes. Note it filters the LAST such date, so a section amended in 2025 is excluded by yearTo=2024 even though it existed in 2024. This is a currency filter, not point-in-time retrieval: the corpus holds one current text per citation.

Drop sections whose own status says they are no longer operative: repealed, renumbered, transferred, recodified, rescinded, revoked, expired, superseded, omitted, reserved, and the rest of the dead and not-operative vocabulary (the full set is the one behind each result's goodLawStatus).

This removes what we KNOW is dead. It does not promise the remainder is good law. A section survives this filter when its status is in_force OR when we hold no trustworthy repeal signal for its jurisdiction, and those two are not the same thing. Read goodLawStatus on each surviving result to tell them apart: good_law is checked, unknown is unchecked. Filtering on the status we store and reporting the verdict we derive are deliberately separate, because only the first is indexable.

The United States Code is served from a stored annual edition (year 2024, currentThrough 2025-01-06), so a section repealed after that edition closed still carries actStatus: in_force and survives this filter. Every USC result therefore reports goodLawStatus: unknown, which is the honest answer and the one this field's second paragraph tells you to read. Use /section/{actId}/changes for the timeline on a section you depend on.

Only return sections we have OBSERVED change on or after this date (YYYY-MM-DD). This is the sync filter: it turns a lookup API into something a nightly job can poll, without creating a board watch per jurisdiction.

These are observed changes, not effective dates. A refresh compared the publisher against the copy we held and found it different; the date is when we SAW it, an upper bound on when it took effect. It is the same event stream GET /us/statutes/section/{actId}/changes serves per section, so a hit here has a history there.

Coverage is bounded by capture, not by the age of the law. Change capture began long after the corpus did, it is per-source, and events are swept at 5 years. An empty result means no captured change in the window, never that nothing was amended.

Narrow with corpusType and state for a tighter window: the change set is resolved to concrete sections before the search runs, and a window matching too many sections is rejected with a 422 that says so rather than silently truncating your answer.

Federal Register document stage: final (a rule in force), proposed (an NPRM), or presidential (a Presidential Document, the EXECUTIVE_ACTION corpus). The same distinction appears in each row's actId prefix (FR_RULE_ vs FR_PRORULE_).

Only return Federal Register documents published on or after this date (YYYY-MM-DD). This is the PUBLICATION date, which is not the same as yearFrom: that filters the version year of a section.

Only return Federal Register documents published on or before this date.

Filter by USC/CFR title number (e.g., 17 for SEC, 42 for civil rights). Only meaningful for USC/CFR; ignored for state corpora whose titles are alphabetic (e.g. Texas pe = Penal Code).

Controls exact vs. semantic matching. any (default) is hybrid semantic + keyword ranking and suits natural-language questions. Use all for strict keyword matching (every query word must appear in the text) or phrase for an exact-phrase match (the query's words, contiguous and in order). Both match WHOLE words, case-insensitively, ignoring punctuation: act does not match fact, 10b-5 matches 10b 5, and § 1983 matches section 1983. Both are answered from the full text of every section in scope, so a section holding the words is found however the relevance ranking would have placed it, and they page like boolean.

boolean reads query as a terms-and-connectors expression and returns ONLY sections that satisfy it, judged over each section's full text, ranked by relevance among them. Operators are UPPERCASE: AND, OR, NOT (negligence NOT criminal), /p same paragraph, /s same sentence, /N within N words (1-255), +p +s +N the same with the first term first, atleastN(term) at least N occurrences, "exact phrase", and bare words side by side are also an exact phrase (summary judgment). Wildcards: retaliat* or retaliat! (any letters or digits), wom?n (one character), with at least 3 characters first. Group with ( ). Precedence follows the convention of legal research services: OR binds tightest, then /N, /s, /p, then AND, then NOT. A malformed expression is a 422 naming the problem and its position, and is not charged; the response's parsedQuery shows how the expression was read. To pull up one specific section, pass its citation as the query with any (e.g. 42 U.S.C. § 1983) and it resolves to that section at rank 1.

Number of results to return per page.

How many results to skip, for paging. Every page of a given query is cut from one ranking, so results never repeat or go missing between pages, and a later page costs no more than the first. any ranks one bounded pool of about 60 sections plus up to about 30 more from the law-specific legs, so roughly 60 to 90 results are reachable and hasMore turns false at the end of that pool, which can be before offset 70. offset is at most 70 there. For exhaustive paging use matchType: "boolean", all or phrase, which page to the end of the matches (up to 10,000): follow nextOffset.

Return the full text of every hit inline, on each result's body, instead of making you fetch it per section afterwards.

Why it exists. Search returns a ranking preview, so the alternative is a search call plus one /section/{actId}/body call per hit. This collapses a whole page to a single round trip.

Cost: the 4-credit search PLUS the ordinary 6-credit body price for each row that actually returns text. Ten rows with text is 4 + 60 = 64 credits. A row whose text cannot be resolved comes back with body: null and is NOT charged, so read creditsConsumed rather than computing it from limit -- it is the same price as fetching them yourself, so this buys latency, not a discount.

⚠️ It multiplies with limit. limit: 50 with this set is 304 credits in a single call. Page deliberately.

Prefer this over raising excerptChars: the excerpt is windowed around the match and can begin mid-section, dropping a leading subsection marker, so it is not safe to quote. body is the publisher's text.

Name the subsection each hit matched, in a pinpoints object keyed by actId. Search ranks whole sections, and a section can run to dozens of subsections; with this set, a hit for 30 mph urban district speed limit comes back with 625 ILCS 5/11-601(c)(1), its own text, the lead-in it completes and its character offsets in the section's plain text.

Cost: none. The price is the search price and creditsConsumed does not change. It never changes which sections are returned, their order or their scores, and it never fails the search: a hit whose subsection cannot be named says why in reason and is still a real match. A subsection is named only when your query's words point at it, so a question put in other words than the law's gets located: false rather than a guess.

Time: adds the time to read each returned section's text, usually a few hundred milliseconds for a page of 10. Pinpoints for a large page stop after a few seconds, and the hits not reached say not_looked_up.

Characters of matching text to include in each result's excerpt. The excerpt is a ranking preview; use /us/statutes/section/{actId}/body for the full text. Default 500.

How many results came back in THIS response, i.e. the length of results. It is not a total match count: the API ranks a bounded set of candidates rather than scoring the whole corpus, so no such total exists. Use hasMore to decide whether to ask for another page. With matchType: "boolean" the total is totalMatches.

DEPRECATED alias for count, kept for backward compatibility. The name reads as a corpus-wide match total, which it never was. Use count instead.

The offset applied to this page.

Whether more results exist beyond this page. For any, all and phrase this is relative to a bounded ranking pool of roughly 60 to 90 sections, so false means the pool is exhausted, not that nothing else in the corpus matches. Use matchType: "boolean" and follow nextOffset to page through every match.

Only present when changedSince is set: how many sections changed in that window, before ranking. Compare it against count. changedSince is a filter on a RANKED search, so a window holding more sections than one query can return is normal and the page you get is the most relevant slice of it, not all of it. When this number is larger than you can page to, the filter is a trigger rather than an inventory: subscribe to the board and poll GET /watches/{id}/changes, which is complete and costs no credits.

True when the relevance model (a cross-encoder) was unavailable and the results are in hybrid-retrieval order instead. The sections are still real matches for the query, but the ordering is coarser and relevanceScore is a retrieval score rather than a 0-1 relevance, so do not threshold on it. Such a ranking is never cached: retrying shortly returns the fully ranked result once the model recovers.

True when nothing in the corpus looks on point for this query. It says nothing about whether the top result is the right section; check its citation and jurisdiction. False when the top result clears the relevance bar, or when the query is a citation or a section number that matched exactly. Null when rankingDegraded is true, because the bar is on the relevance model's scale. The same on every page of a query.

How strongly the evidence says result #1 answers the query. exact: a citation or section-number match. strong: the top result was correct about 94% of the time in our measurements (about 91% on questions whose answer is a statute or regulation). moderate: about 67%. weak: about 35%. none: nothing on point (same as noGoodMatch). Measured on our labelled evaluation set; tiers may be re-cut as the index changes, so treat unknown values as moderate. Null when rankingDegraded is true. The same on every page of a query.

Present only with matchType: "boolean": the expression as it was read, in canonical form with explicit operators and grouping, e.g. (work OR employment) AND retaliation. Paste it back to run the same search.

Present only with matchType: "boolean": how many sections satisfy the expression within your filters, across ALL pages, not just this one. Read it with totalMatchesExact. Absent when it could not be counted in time. The same on every page of a query.

Present with totalMatches. True: it is the exact number of matching sections (a section the corpus holds under two ids, such as a Federal Rule kept in two collections, counts twice and is served once). False: it is an UPPER BOUND, because the expression uses an operator the count cannot judge exactly (phrases, /s, /p, proximity, atleastN, wildcards inside proximity) or a filter the count does not apply (anything beyond corpusType, state, actStatus and excludeRepealed); every served row still satisfies the expression.

Present only with matchType: "boolean": how many leading results (at most 120) are ordered by the relevance model. Results after them continue in keyword (BM25) order and repeat the last ranked relevanceScore, so every match can be paged to without being re-scored.

Present only with matchType boolean, all or phrase while hasMore is true: the offset to send for the next page. Usually offset + limit. Past the relevance-ranked results a page can hold fewer rows than limit (candidates outside your filters, or failing the expression on full-text verification, are left out), and when verification runs out of time the page stops early and nextOffset resumes exactly where it stopped. Follow it rather than computing the offset. For any the field is absent: while hasMore is true, request the next page with offset + limit.

Present only with matchType: "any" when the query is written in Boolean syntax (an UPPERCASE AND/OR/NOT between words, a proximity connector such as /s or /5, or atleastN(). The search was NOT run as Boolean: retry with matchType: "boolean" to apply the operators.

Present only when the request set includePinpoint: true and no pinpoints were looked up for this page, with the reason: the relevance model was unavailable (rankingDegraded), the candidate pool was incomplete (so the results are a coarser answer), or the pinpoint step itself failed (lookup_failed). Retry shortly for the full one. The search is charged as usual.

Present only when this page is SHORT because that many ranked hits could not be loaded or serialized on our side and were left out: count is then smaller than the page the ranking chose. It is a fault, not a filter, and says nothing about whether those sections exist; repeat the call to get them. Absent on a complete page.

Present only when includeBody: true was set and the bodies were withheld because the balance could not cover them (each row says bodyNote: insufficient_credits). The ranking was served and billed as usual; no body was charged.

The search query used.

Server-side time for this request in milliseconds, excluding network transit. Useful for spotting a slow query; not billed on.

Credits actually charged for this call. Read it rather than assuming the list price: failed and refunded work bills 0, and batch endpoints charge per item returned, so a partial result costs less than a full one.