Race Matchup
race_matchupOne US House district or Senate seat: who the sitting officeholder is (incumbent, with seeking_reelection and incumbent_note saying whether they are actually on the ballot or the seat is open), every FEC-registered candidate by party with money raised/spent/cash on hand, which candidates won their primary, primary and general election dates. Primary vote counts come from Wikipedia (non-official, labelled as such, cites the state election authority); money and incumbency are FEC. A district that does not exist returns an error naming the districts that do.
Example tool call
This call uses example arguments supplied in the tool’s input schema.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"state": "IA",
"office": "house",
"district": 1
},
"name": "race_matchup"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cycle | No | Election year, even. Default 2026. | |
| state | Yes | US state: postal code ("IA") or full name ("Iowa"). | |
| office | Yes | "house" or "senate". | |
| special | No | Senate only: read the special-election primary page (Ohio and Florida in 2026). | |
| district | No | House district number (1, "01") or "at-large". Required for house, ignored for senate. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| race | No | ||
| cycle | No | ||
| source | No | ||
| incumbent | No | ||
| candidates | No | ||
| data_as_of | No | ||
| election_dates | No | ||
| incumbent_note | No | ||
| candidates_note | No | ||
| data_as_of_note | No | ||
| primary_results | No | ||
| candidates_total | No | ||
| won_primary_note | No | ||
| primary_results_note | No | ||
| candidates_money_note | No | ||
| primary_results_source | No |