List Actors
list_actorsActors (congresistas, ministros, legisladores, funcionarios) — list, search, or fetch one profile by id, in a single tool. Authoritative roster sourced directly from each congress's official directory.
No id (default): paginated roster across country_code (comma-separated; omit for every accessible/your default country). Use q to resolve a name to its id — accent/case-insensitive, and every token just has to appear somewhere in the full name, so q="braulio espinal" finds 'Braulio de Jesús Espinal Tavárez'. Use branch="executive" for ministers/government officials instead of congresistas (⚠️ coverage heavily skewed to Brazil today) or commission_id for 'members of Comisión X' questions.
Counting seats ('¿cuántos senadores tiene MIRA?', 'does La Libertad Avanza have a majority?'): combine party_id (from list_parties) with chamber, then read meta.total — it counts every match, not just this page, so never paginate a roster and tally rows yourself. chamber is token-matched against the chamber's name ('senado', 'camara', 'diputados'); chambers are named differently per country and every row carries its own chamber, so use those values as the vocabulary. For a majority question, run the same count without party_id to get the chamber's size.
With id: ignores every other filter and returns a complete profile in one call — actor detail (name, party, commissions, social links, current_position, CV) + up to 10 most recent votes + up to 5 most recently filed bills. Replaces the old get_actor + list_actor_votes + list_actor_bills call sequence. For more than 10 votes / 5 bills, or for interventions/tweets, use list_votes(actor_id=...), list_bills(actor_id=...), list_interventions(actor_id=...), or list_actor_tweets(id=...) directly.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Search by name. Accent/case-insensitive, and every token just has to appear somewhere in the full name, so 'braulio espinal' finds 'Braulio de Jesús Espinal Tavárez'. | |
| id | No | An actor's own id. Set it for that one person's full profile plus recent votes and bills; 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. | |
| branch | No | 'executive' for ministers and government officials, 'legislative' for congresistas with an active mandate. Executive coverage is heavily skewed to Brazil today. | |
| 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. | |
| chamber | No | Chamber name, token-matched and accent/case-insensitive: 'senado', 'camara', 'diputados', 'asamblea'. Chambers are named differently per country and every row carries its own `chamber`, so use those values as the vocabulary. Excludes anyone with no active mandate. | |
| party_id | No | Members of this party (list_parties to discover IDs). Combine with `chamber` and read `meta.total` to answer seat counts. | |
| has_mandate | No | Filter by whether the person currently holds a seat. Brazil's roster carries many real people with no active mandate — former candidates and officials — and counting 'diputados del partido X' counted them. Leave unset to see everyone (executive-branch actors have no mandate row by construction, so a default would empty branch='executive'); every row carries `has_mandate`, which is how you know whether you need this. | |
| 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 | Members of this commission (list_commissions to discover IDs). Matches both the actor's primary commission and any additional ones. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||