---
title: "List actors"
method: GET
path: "/v1/actors"
tags: ["Actors"]
---

# List actors

`GET /v1/actors`

## Request

- Base URL: `https://api.dapperglobal.com`
- URL: `https://api.dapperglobal.com/v1/actors`
- Auth: API key in header `X-API-Key`

Authoritative roster of political actors (congresistas, legisladores, funcionarios), sourced directly from each congress's official directory (see 'Data sources' below). Use it for questions like 'who are the members of the Comisión de Hacienda in Perú?' or 'legisladores del partido X en Colombia' — filter here.

Paginated across countries. `country_code` is comma-separated (e.g. `BR,CO`); omit to return all accessible countries. Each actor includes their party and current commissions. To get full context on a specific actor (profile + recent votes + recent bills in one call) use `get_actor_summary(actor_id)`.

Don't know the actor_id? Use `q` to resolve a name to it first — accent/case/whitespace-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` to find ministers/government officials instead of congresistas (e.g. 'who are Colombia's ministers?' → list_actors(country_code="CO", branch="executive")) — the specific role (e.g. 'Ministro/a de Hacienda') is on `current_position` in get_actor's response, not on the list. ⚠️ Executive-branch coverage is real but heavily skewed to Brazil today (see the Actors 'Data sources' note).

Use `commission_id` for 'who are the members of Comisión X' type questions — use list_commissions(country_code=...) to discover valid IDs.

For seat-count questions ('¿cuántos senadores tiene MIRA?', 'does La Libertad Avanza have a majority?') combine `party_id` with `chamber` and read `meta.total` — it counts every matching actor, not just the current page, so there is no need to paginate a whole roster and tally rows.

**Data sources:** official rosters of each national congress and government directory — name, party affiliation, and commission memberships as published by the chambers. Executive-branch officials (ministers, government agency heads) are also actors here, filterable with `branch=executive`; that coverage is real but heavily skewed to Brazil as of 2026-07-28. ⚠️ No source-document URL is available for the actor record itself (only `social_links`, which are the actor's own accounts, not a data-provenance link) — cite this actor's `votes` or `bills` instead when a primary-source link is needed.

## Query parameters

- `limit` integer
- `cursor` string, nullable
- `q` string, nullable: Search by name — accent/case/whitespace-insensitive, every token must appear somewhere in the full name, in any order, e.g. q='braulio espinal' matches 'Braulio de Jesús Espinal Tavárez'.
- `branch` string, nullable: Filter by branch of government: 'executive' (ministers/government officials) or 'legislative' (congresistas with an active mandate).
- `commission_id` integer, nullable: Filter to actors who are members of this commission. Use list_commissions() to discover valid IDs. Matches on both commission mechanisms — the actor's primary commission and any additional ones.
- `party_id` integer, nullable: Filter to actors belonging to this party. Use list_parties(country_code=...) to discover valid IDs. Combine with `chamber` to answer seat-count questions ('¿cuántos senadores tiene el partido X?') — read `meta.total` for the count rather than paginating and tallying rows yourself.
- `chamber` string, nullable: Filter by chamber, matched against the chamber's name (accent/case-insensitive, all tokens must appear): 'senado', 'camara', 'diputados', 'asamblea'. Chamber names differ per country — every row you get back carries its own `chamber`, so use those values as the vocabulary. Actors with no active legislative mandate (ministers, candidate stubs) have no chamber and are excluded when this is set.
- `has_mandate` boolean, nullable: Filter by whether the person currently holds a seat. Measured on the replica, Brazil's roster is full of real people with no active mandate — former candidates and officials — and a caller counting 'diputados del partido X' counted them. Leave unset to see everyone (executive-branch actors never have a mandate row, so a default would empty branch='executive'); every row carries `has_mandate` so you can see whether you need this.
- `country_code` string, nullable: Comma-separated country codes, e.g. BR,CO,CL.
- `country_id` string, nullable: Deprecated alias: comma-separated numeric ids, e.g. 8,2,6.

## Response `200`

Successful response (real sample data)

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/dapperglobal/apis/dapper-political-intelligence-api.md) · [All operations](https://skmtc.dev/dapperglobal/apis/dapper-political-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dapperglobal/apis/dapper-political-intelligence-api/revisions/f34d9e6a2b0e?raw)