---
title: "GET /v1/candidates/totals/"
method: GET
path: "/v1/candidates/totals/"
tags: ["candidate"]
---

# GET /v1/candidates/totals/

`GET /v1/candidates/totals/`

## Request

- Base URL: `https://api.open.fec.gov` (the document declares no server; this is the origin it was published from)
- URL: `https://api.open.fec.gov/v1/candidates/totals/`
- Auth: API key in header `X-Api-Key` and API key in query parameter `api_key` and API key in query parameter `api_key`
- TypeScript: <https://skmtc.dev/fec/apis/openfec/docs/v1/candidates/totals/get.ts> (a function with typed inputs; its response is checked against the schema)

Aggregated candidate receipts and disbursements grouped by cycle.

## Query parameters

- `page` integer
- `per_page` integer
- `q` string[]
- `candidate_id` string[]
- `election_year` integer[]
- `cycle` integer[]
- `office` string[]
- `election_full` boolean
- `state` string[]
- `district` string[]
- `party` string[]
- `min_receipts` number
- `max_receipts` number
- `min_disbursements` number
- `max_disbursements` number
- `min_cash_on_hand_end_period` number
- `max_cash_on_hand_end_period` number
- `min_debts_owed_by_committee` number
- `max_debts_owed_by_committee` number
- `federal_funds_flag` boolean
- `has_raised_funds` boolean
- `is_active_candidate` boolean
- `sort` string
- `sort_hide_null` boolean
- `sort_null_only` boolean
- `sort_nulls_last` boolean
- `api_key` string

## Response `default`

Default response

- CandidateHistoryTotalPage
  - `pagination` OffsetInfo
    - `count` integer
    - `is_count_exact` boolean
    - `page` integer
    - `pages` integer
    - `per_page` integer
  - `results` CandidateHistoryTotal[]
    - `active_through` integer, nullable: Last year a candidate was active. This field is specific to the candidate_id so if the same person runs for another office, there may be a different record for them.
    - `address_city` string, nullable: City of candidate's address, as reported on their Form 2.
    - `address_state` string, nullable: State of candidate's address, as reported on their Form 2.
    - `address_street_1` string, nullable: Street of candidate's address, as reported on their Form 2.
    - `address_street_2` string, nullable: Additional street information of candidate's address, as reported on their Form 2.
    - `address_zip` string, nullable: Zip code of candidate's address, as reported on their Form 2.
    - `candidate_election_year` integer, nullable: The last year of the cycle for this election.
    - `candidate_first_name` string, nullable: First name of candidate running for office
    - `candidate_id` string, required: A unique identifier assigned to each candidate registered with the FEC. If a person runs for several offices, that person will have separate candidate IDs for each office. First character indicates office - [P]residential, [H]ouse, [S]enate]. Second character is the last digit of the two-year period the ID was created. Third and fourth is the candidate state. Presidential IDs don't have state. Fifth and sixth is the district when the candidate first ran. This does not change if the candidate/member's district changes during re-districting. Presidential IDs don't have districts. The rest is sequence.
    - `candidate_inactive` boolean, nullable: True indicates that a candidate is inactive.
    - `candidate_last_name` string, nullable: Candidate last name
    - `candidate_middle_name` string, nullable: Middle name of candidate running for office
    - `candidate_prefix` string, nullable: Name prefix of candidate running for office
    - `candidate_status` string, nullable: One-letter code explaining if the candidate is: - C present candidate - F future candidate - N not yet a candidate - P prior candidate
    - `candidate_suffix` string, nullable: Name suffix of candidate running for office
    - `cash_on_hand_end_period` number, nullable: Ending cash balance on the most recent filing
    - `coverage_end_date` string, date, nullable: Ending date of the reporting period
    - `coverage_start_date` string, date, nullable: Beginning date of the reporting period
    - `cycle` integer, required: Filter records to only those that are applicable to a given two-year period. This cycle follows the traditional House election cycle and subdivides the presidential and Senate elections into comparable two-year blocks. The cycle begins with an odd year and is named for its ending, even year.
    - `cycles` integer[], nullable: Two-year election cycle in which a candidate runs for office. Calculated from Form 2. The cycle begins with an odd year and is named for its ending, even year. This cycle follows the traditional house election cycle and subdivides the presidential and Senate elections into comparable two-year blocks. To retrieve data for the entire four years of a presidential term or six years of a senatorial term, you will need the `election_full` flag.
    - `debts_owed_by_committee` number, nullable: Debts owed by the committee
    - `disbursements` number
    - `district` string, nullable: Two-digit US House distirict of the office the candidate is running for. Presidential, Senate and House at-large candidates will have District 00.
    - `district_number` integer, nullable: Two-digit US House distirict of the office the candidate is running for. Presidential, Senate and House at-large candidates will have District 00.
    - `election_districts` string[], nullable: Two-digit US House distirict of the office the candidate is running for. Presidential, Senate and House at-large candidates will have District 00.
    - `election_year` integer: Year of election
    - `election_years` integer[], nullable: Years in which a candidate ran for office.
    - `fec_cycles_in_election` integer[], nullable: FEC cycles are included in candidate election years.
    - `federal_funds_flag` boolean, nullable: A boolean the describes if a presidential candidate has accepted federal funds. The flag will be false for House and Senate candidates.
    - `first_file_date` string, date, nullable: The day the FEC received the candidate's first filing. This is a F2 candidate registration.
    - `flags` unknown
    - `has_raised_funds` boolean, nullable: A boolean that describes if a candidate's committee has ever received any receipts for their campaign for this particular office. (Candidates have separate candidate IDs for each office.)
    - `incumbent_challenge` string, nullable: One-letter code ('I', 'C', 'O') explaining if the candidate is an incumbent, a challenger, or if the seat is open.
    - `incumbent_challenge_full` string, nullable: Explains if the candidate is an incumbent, a challenger, or if the seat is open.
    - `individual_itemized_contributions` number
    - `is_election` boolean, required
    - `last_f2_date` string, date, nullable: The day the FEC received the candidate's most recent Form 2
    - `last_file_date` string, date, nullable: The day the FEC received the candidate's most recent filing
    - `load_date` string, date-time, nullable: Date the information was loaded into the FEC systems. This can be affected by reseting systems and other factors, refer to receipt_date for the day that the FEC received the paper or electronic document. Keep in mind that paper filings take more time to process and there can be a lag between load_date and receipt_date. This field can be helpful to identify paper records that have been processed recently.
    - `name` string, nullable: Name of candidate running for office
    - `office` string, nullable: Federal office candidate runs for: H, S or P
    - `office_full` string, nullable: Federal office candidate runs for: House, Senate or presidential
    - `other_political_committee_contributions` number
    - `party` string, nullable: Three-letter code for the party affiliated with a candidate or committee. For example, DEM for Democratic Party and REP for Republican Party.
    - `party_full` string, nullable: Party affiliated with a candidate or committee
    - `receipts` number
    - `rounded_election_years` integer[], nullable: Rounded election years in which a candidate ran for office
    - `state` string, nullable: US state or territory where a candidate runs for office
    - `state_full` string, nullable: US state or territory where a candidate runs for office
    - `transfers_from_other_authorized_committee` number
    - `two_year_period` integer, required: Two-year election cycle in which a candidate runs for office. Calculated from Form 2. The cycle begins with an odd year and is named for its ending, even year. This cycle follows the traditional house election cycle and subdivides the presidential and Senate elections into comparable two-year blocks. To retrieve data for the entire four years of a presidential term or six years of a senatorial term, you will need the `election_full` flag.

---

[API](https://skmtc.dev/fec/apis/openfec.md) - [All operations](https://skmtc.dev/fec/apis/openfec/llms.txt) - [OpenAPI document](https://skmtc.dev/fec/apis/openfec/revisions/d2eb3171e225?raw)