List Consultations
list_consultationsPublic consultations (consultas públicas) — list, search, or fetch one by id, in a single tool. Authoritative data from official consultation portals and ministry sites. No body/summary field — only title, dates, and external_link; for the substance, follow external_link to the source.
No id (default): paginated list across country_code (comma-separated; omit for every accessible/your default country), newest-published first by default; order_by="end_date" lists the ones closing soonest first (pair it with status="open"), across pages. Filter by since/until (publication date) or closing_before/closing_after/status (vigencia, end_date) — e.g. status="open" for consultations still accepting comments. Use entity_id for '¿qué consultas públicas abrió ?' — resolve the name with list_entities(q="") first (comma-separated for several); every row also carries its own entity_id/entity_name. Use q to search by title or meaning — tries the hybrid/semantic engine first, falls back to a title match where every token must appear; semantic hits carry a relevance score and anything at or below min_similarity (default 0.5) is dropped rather than returned as filler.
With id: ignores every other filter and returns full detail — title, description, publication window, and external_link.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Search by title or meaning. Semantic first, then a title match requiring every token in any order. | |
| id | No | A consultation's own id. Set it for full detail; every other filter is ignored. | |
| 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 | Published on or after this date (YYYY-MM-DD). This is the publication date, not the closing date — use closing_before/closing_after for that. | |
| until | No | Published 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. | |
| status | No | 'open' = still accepting comments (end_date in the future, or unknown); 'closed' = past its end_date. | |
| order_by | No | 'ingested' (default): newest-published first. 'end_date': closing soonest first — with status='open', 'what closes next'. 'end_date_desc': latest closing date first. With `q`, the semantic page is re-sorted by it. A cursor only continues the order it came from. | ingested |
| entity_id | No | Issuing agency ID; several as '21,44' or [21, 44]. This is how you answer '¿qué consultas abrió <agencia>?' — resolve the name with list_entities(q='<name>') first. | |
| 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`. | |
| closing_after | No | Closes (end_date) on or after this date. | |
| closing_before | No | Closes (end_date) on or before this date. For 'closing in the next N days', pass status='open' plus closing_before=<today+N>. | |
| 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 | |||