# 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.

- Page: https://fous.com/methods/ballotpedia.org/get-candidate
- Method: `ballotpedia.org/get_candidate`, version 1
- Website: ballotpedia.org
- Returns: full name, party, current office, state, biography, elections, campaign themes, websites, social links, photo, other matches
- Effect: read (it gets data and changes nothing)
- Sign-in: none needed
- Cost: 1 credit per completed run (1¢ with pay as you go); failed runs are free
- Verified: Nov 2, 2026

## Inputs

| Field | Type | Required | In the run below | Description |
|---|---|---|---|---|
| `name` | string | yes | `"Alexandria Ocasio-Cortez"` | Candidate or officeholder name, for example Alexandria Ocasio-Cortez. |
| `state` | string | no |  | Optional state name or two-letter code to distinguish candidates, for example New York or NY. |

## Output

From a run on Oct 31, 2026, shortened. Its input:

```json
{
  "name": "Alexandria Ocasio-Cortez"
}
```

Its output:

```json
{
  "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."
  ]
}
```

## Run it

From code, with a Fous API key in `FOUS_API_KEY`; the answer's `data` holds the output:

```bash
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"}}'
```

From an AI agent connected to the Fous MCP server: its `run` with the same method and input. To connect one, give it `set up https://fous.com/SKILL.md`.

## 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.

## Input schema

```json
{
  "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

```json
{
  "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"
      }
    }
  }
}
```

## See more

- [Ballotpedia API: List ballot measures](https://fous.com/methods/ballotpedia.org/list-ballot-measures.md): Lists 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.
- [ORCID API: Get researcher profile](https://fous.com/methods/orcid.org/get-researcher.md): Looks 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.
- [FEC API: Get candidate fundraising](https://fous.com/methods/fec.gov/get-candidate-fundraising.md): Gets 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.
- [IMDb API: Get film person](https://fous.com/methods/imdb.com/get-person.md): Finds 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).
- [X API: Get profile](https://fous.com/methods/x.com/get-profile.md): Gets the public X profile for a username or profile link, including counts, verification, images and account details. Does not include posts or a timeline.
- [Bluesky API: Get profile](https://fous.com/methods/bsky.app/get-profile.md): Looks 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.
- [NBA API: Get player by name](https://fous.com/methods/nba.com/get-player.md): Looks 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.
- [OpenTable API: Get restaurant profile](https://fous.com/methods/opentable.com/get-restaurant.md): Gets 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.
- [All Ballotpedia methods](https://fous.com/methods/ballotpedia.org.md)