List Bills
list_billsBills (proyectos de ley) — list, search, or fetch one by id, in a single tool. Authoritative, primary-source data sourced directly from each congress's official docket system, refreshed daily. Use it for 'reforma pensional Colombia trámite actual' type questions.
Counting? A list without q reports meta.total — every bill matching the filters, not just this page — so '¿cuántos proyectos se radicaron en 2025 en Brasil?' is one call with since/until and limit=1. It is null when you pass q (a relevance search returns a top-K, not a filtered set) and on pages after the first, where the total from page 1 still holds.
No id (default): paginated list, newest filing date first, across country_code (comma-separated, e.g. BR,CO; omit for every accessible country — or, logged in via OAuth, your own default country). Filter by commission_id, party_id (use list_parties to discover IDs — matches if any active author currently belongs to that party, e.g. 'proyectos de la bancada de Centro Democrático' without iterating every one of that party's legislators through list_actors first), or a since/until date range. Every row carries authors and latest_state, so 'who filed the most bills' and 'what did one chamber approve that the other still has' are answerable from the list itself — no per-bill round-trip. ⚠️ Author coverage varies sharply: ~91% of Colombian and Peruvian bills have one, but only ~28% in Brazil, Chile and Rep. Dominicana and 0% in Venezuela, so an empty authors is usually a gap rather than a bill with no author.
Have the bill's number? Use code, not q — e.g. code="24509", code="045/2026C", code="05989-2024-2028-CD". It matches the official expediente in congress_records[].code, as a substring or number-for-number with leading zeros ignored. Numbers are not part of the title, so putting one in q doesn't just fail to help — it actively breaks the search.
Only know the topic? Use q — tries the hybrid/semantic engine first (matches by meaning), falls back to a title match where every token must appear, in any order. Semantic hits carry rerank, the cross-encoder's verdict: cite by it, and treat a negative one as rejected. relevance is the raw cosine and does not separate good hits from bad. Use actor_id to get bills authored by one legislator instead (ignores commission_id/q/since/until — the underlying query has no date/commission facet on authored bills).
With id: ignores every other filter and returns a full overview in one call — bill detail (title, type, source, congress_records) + up to 200 tramitaciones (legislative updates, ordered) + vote_summary (every vote counted per tramitación as for/against/abstained/absent, with the raw values) + a sample of up to 20 individual votes + up to 10 related interventions (small dataset today — see interventions_coverage when empty). Replaces the old get_bill + list_bill_updates + list_bill_votes + list_bill_interventions call sequence. For more than the capped 200 updates / 20 votes / 10 interventions on one bill, use list_bill_updates(bill_id=...) or list_votes(bill_id=...) / list_interventions(bill_id=...) directly.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Search by topic or meaning, e.g. 'transición energética'. Do NOT put a bill number here — use `code`. Semantic first, then a title match requiring every token in any order. | |
| id | No | A bill's own id. Set it to get that one bill's full overview (detail + tramitaciones + votes + interventions) and every other filter is ignored. | |
| code | No | The official congress code/expediente, e.g. '24509', '045/2026C', '05989-2024-2028-CD' — the same value returned in `congress_records[].code`. Matches as a substring or number-for-number with leading zeros ignored. Use this whenever you have a number. | |
| limit | No | Rows per page (1-100, default 20). The response's `meta.has_more` and `meta.next_cursor` tell you whether there are more. `meta.total`, when it is not null, is the full count without paging; some lists return null rather than pay for a count. Raise the limit when you genuinely need a whole list in one call rather than the most relevant few. | |
| since | No | Filed on or after this date (YYYY-MM-DD). Filters filing_date, the date the bill was formally presented. | |
| until | No | Filed on or before this date (YYYY-MM-DD). | |
| cursor | No | Opaque pagination cursor from a previous response's `meta.next_cursor`. Pass every other filter unchanged when paging. Only ever use a cursor this API handed you — never build one. With `q`, a cursor continues the keyword listing (`meta.mode: "keyword_fallback"`): relevance-ranked results are a single page of at most 20 rows and report `has_more: false`, so if you got one there is no next page to ask for, and a `limit` above 20 adds nothing to it. Narrow `q` instead of paging. | |
| actor_id | No | Bills authored by this legislator. Ignores commission_id/q/since/until — the underlying query has no date or commission facet on authored bills. | |
| party_id | No | Bills with at least one active author currently in this party (list_parties to discover IDs). It's the author's party, not the bill's, so a bill co-authored across parties matches any of them. | |
| min_rerank | No | Cross-encoder floor for the semantic branch of `q`. Rows the reranker scores below this are dropped; if that empties the result, what was rejected comes back under `empty_result.near_misses` so you can see what the index does hold. Pass null to disable the filter entirely. | |
| country_code | No | ISO alpha-2 country codes, comma-separated or as a list: 'BR,CO' or ['BR','CO']. Pass 'all' for every country you can access. Omitting it is NOT the same as 'all': logged in via OAuth it falls back to your own default country, and the response says so in `meta.country_scope`. | |
| commission_id | No | Commission the bill has passed through (list_commissions to discover IDs). Structural, not time-scoped — it does not tell you what a commission decided this week; use list_bill_updates for that. | |
| min_similarity | No | Cosine-similarity floor for the semantic branch of `q` (0-1). A coarse filter only: measured on production, 58% of the rows that clear it are then rejected by the cross-encoder, and the two score ranges overlap almost completely — `min_rerank` is the parameter that actually discriminates. Lower this to widen a search that came back empty. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||