Ballotpedia API: Get candidate profile
Looks up a Ballotpedia candidate or officeholder profile by name, with election results, background and published links. An optional state narrows people with the same name; unreported details are left blank.
Unofficial. Not affiliated with or endorsed by Ballotpedia.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- Name, required
name Candidate or officeholder name, for example Alexandria Ocasio-Cortez.
Alexandria Ocasio-Cortez
- State optional
state Optional state name or two-letter code to distinguish candidates, for example New York or NY.
Not set
Input as JSON
{ "name": "Alexandria Ocasio-Cortez"}Output
{ "party": "Democratic Party", "state": "New York", "biography": "Alexandria Ocasio-Cortez graduated from Boston University College of Arts & Sciences in 2011 with a Bachelor of Arts degree in international relations and economics. She was a volunteer organizer for Sanders' presidential campaign and worked in former Sen. Ted Kennedy's (D-Mass.) foreign affairs and…", "elections": [ { "year": 2026, "stage": "Primary", "office": "U.S. House New York District 14", "result": "Won", "vote_percentage": 86.9, "ballotpedia_link": "https://ballotpedia.org/Alexandria_Ocasio-Cortez#2026" }, { "year": 2024, "stage": "General", "office": "U.S. House New York District 14", "result": "Won", "vote_percentage": 68.9, "ballotpedia_link": "https://ballotpedia.org/Alexandria_Ocasio-Cortez#2024" }, { "year": 2024, "stage": "Primary", "office": "U.S. House New York District 14", "result": "Won", "vote_percentage": 81.8, "ballotpedia_link": "https://ballotpedia.org/Alexandria_Ocasio-Cortez#2024" } ], "full_name": "Alexandria Ocasio-Cortez", "photo_link": "https://s3.amazonaws.com/ballotpedia-api4/files/thumbs/200/300/Alexandria_Ocasio-Cortez.jpg" , "office_since": "2019-01-03", "other_matches": [], "current_office": "U.S. House New York District 14", "ballotpedia_link": "https://ballotpedia.org/Alexandria_Ocasio-Cortez" , "campaign_website": "https://www.ocasiocortez.com" , "official_website": "https://ocasio-cortez.house.gov/" , "social_media_links": [ { "link": "https://www.facebook.com/repAOC/" , "platform": "Facebook", "account_type": "Official" }, { "link": "https://x.com/RepAOC" , "platform": "X", "account_type": "Official" }, { "link": "https://www.instagram.com/repaoc/" , "platform": "Instagram", "account_type": "Official" } ], "key_positions_or_campaign_themes": [ "During her campaign, Ocasio-Cortez said she supported policies including universal Medicare, free tuition for public college and trade school, 100% renewable energy, abolishing Immigration and Customs Enforcement (ICE) , and a federal jobs guarantee." ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"ballotpedia.org/get_candidate","input":{"name":"Alexandria Ocasio-Cortez"}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "ballotpedia.org/get_candidate" , "input": { "name": "Alexandria Ocasio-Cortez" }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "ballotpedia.org/get_candidate" , "input": { "name": "Alexandria Ocasio-Cortez" } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run ballotpedia.org/get_candidate# with {"name":"Alexandria Ocasio-Cortez"}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Candidate or officeholder name, for example Alexandria Ocasio-Cortez." }, "state": { "type": "string", "description": "Optional state name or two-letter code to distinguish candidates, for example New York or NY." } }}Output schema
{ "type": "object", "required": [ "full_name", "party", "current_office", "office_since", "state", "biography", "elections", "key_positions_or_campaign_themes", "campaign_website", "official_website", "social_media_links", "photo_link", "ballotpedia_link", "other_matches" ], "properties": { "party": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "biography": { "type": [ "string", "null" ] }, "elections": { "type": "array", "items": { "type": "object", "required": [ "year", "office", "stage", "result", "vote_percentage", "ballotpedia_link" ], "properties": { "year": { "type": "integer" }, "stage": { "type": "string" }, "office": { "type": "string" }, "result": { "type": "string" }, "vote_percentage": { "type": [ "number", "null" ] }, "ballotpedia_link": { "type": "string" } } } }, "full_name": { "type": "string" }, "photo_link": { "type": [ "string", "null" ] }, "office_since": { "type": [ "string", "null" ], "format": "date" }, "other_matches": { "type": "array", "items": { "type": "object", "required": [ "name", "ballotpedia_link" ], "properties": { "name": { "type": "string" }, "ballotpedia_link": { "type": "string" } } } }, "current_office": { "type": "string" }, "ballotpedia_link": { "type": "string" }, "campaign_website": { "type": [ "string", "null" ] }, "official_website": { "type": [ "string", "null" ] }, "social_media_links": { "type": "array", "items": { "type": "object", "required": [ "platform", "account_type", "link" ], "properties": { "link": { "type": "string" }, "platform": { "type": "string" }, "account_type": { "type": "string" } } } }, "key_positions_or_campaign_themes": { "type": "array", "items": { "type": "string" } } }}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
ballotpedia.org/get_candidate- Returns
- full name, party, current office, state, biography, elections, campaign themes, websites, social links, photo, other matches
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method ballotpedia.org/get_candidate with the inputs above.
Ask your agent
- Pull up the Ballotpedia profile for Raphael Warnock, including his past election results and campaign website.
- Who is Mark Kelly from Arizona? I need his party, current office, and a short bio.
- Find the candidate John Smith running in Texas and list his campaign themes and social media accounts.
- What elections has Gretchen Whitmer run in and what were the results? Check Ballotpedia for her record.
- Get background info on Katie Porter in CA: photo, official websites, and any other people with the same name.
See more
All Ballotpedia methodsLists statewide ballot measures in a US state and year, in Ballotpedia order, with election dates, topics, measure types, yes/no vote meanings and results. Years without statewide measures return an empty list.
ballotpedia.org/list_ballot_measuresLooks up a researcher's public ORCID profile by name or ORCID iD, with employment, education, funding and up to 100 works. An institution helps tell namesakes apart; private entries are left out.
orcid.org/get_researcherGets a federal candidate's fundraising and spending for a two-year FEC cycle. If several names match, returns the match with the most reported receipts.
fec.gov/get_candidate_fundraisingFinds a film person on IMDb by name, IMDb person link or person ID and returns their biography, awards summary, known-for titles and filmography (without self-appearances, archive footage and thanks).
imdb.com/get_personGets the public X profile for a username or profile link, including counts, verification, images and account details. Does not include posts or a timeline.
x.com/get_profileLooks up a public Bluesky profile by handle or profile link, including bio, audience counts and join date. A bare name first checks its .bsky.social handle, then the top relevant people-search result.
bsky.app/get_profileLooks up an NBA player by name, including retired players, and returns the bio and regular-season per-game averages for the reported season and career.
nba.com/get_playerGets a restaurant's public OpenTable profile by name or OpenTable link and city, including ratings, details, menu and photo links. Ratings and other fields can be missing when the restaurant does not publish them.
opentable.com/get_restaurant