API Reference

Base URL: https://poltrapro.com/api/v1 · Version: 1

Authentication

All requests require an API key passed as a Bearer token in the Authorization header. Get a free key at poltrapro.com/developers.

curl -H "Authorization: Bearer ptpk_live_YOUR_KEY" \
  "https://poltrapro.com/api/v1/candidates"

Keep your API key secret. Do not expose it in client-side code or public repositories. If compromised, contact support@poltrapro.com to reset it.

Rate Limits

Rate limits are enforced per API key per calendar day (UTC). Exceeding the limit returns a 429 response. Limits reset at midnight UTC.

Tier	Requests / day	Price
`free`	100	Free
`hobby`	1,000	$29/mo
`pro`	10,000	$99/mo
`enterprise`	Unlimited	Contact us

Errors

All errors return JSON with an error field describing the problem.

Status	Meaning
`401`	Missing, malformed, or invalid API key
`404`	Candidate not found. Use /candidates to search.
`429`	Rate limit exceeded for your tier
`500`	Server error — try again shortly

GET /candidates

Search and filter tracked candidates. Returns lightweight summaries with a profileUrl for fetching full data.

GET /api/v1/candidates
Authorization: Bearer ptpk_live_YOUR_KEY

Query parameters

state

string

Two-letter state code. Example: FL, TX, NY

office

string

Partial match. Example: Senate, House, Governor

party

string

Republican, Democrat, or Independent

level

string

federal or state

q

string

Name search — partial match

limit

integer

Max results. Default 50, max 200

offset

integer

Pagination offset. Default 0

Example

curl -H "Authorization: Bearer ptpk_live_YOUR_KEY" \
  "https://poltrapro.com/api/v1/candidates?state=FL&office=Senate"

{
  "data": [
    {
      "id": "ashley-moody",
      "name": "Ashley Moody",
      "party": "Republican",
      "office": "U.S. Senate",
      "state": "FL",
      "level": "federal",
      "fecId": "S6FL00640",
      "congressBioId": "M001244",
      "profileUrl": "/api/v1/candidate/ashley-moody/profile",
      "publicUrl": "https://poltrapro.com/candidate/ashley-moody"
    }
  ],
  "total": 1,
  "pagination": { "limit": 50, "offset": 0, "hasMore": false }
}

GET /candidate/:id/profile

The core joined endpoint. Returns all available data for a candidate in a single response — finance, legislation, outside spending, and prediction market odds pre-joined server-side.

GET /api/v1/candidate/:id/profile
Authorization: Bearer ptpk_live_YOUR_KEY

Path parameters

idrequired

string

Candidate slug from /candidates. Example: ashley-moody, jon-ossoff

Response fields

finance.totalRaised

number

Total campaign receipts in the current cycle (FEC)

finance.burnRate

number

Percent of raised funds spent. Derived: totalSpent/totalRaised × 100

finance.pacShare

number

Percent of funds from PACs. Derived: pacContributions/totalRaised × 100

legislation.sponsored

array

Bills sponsored by this candidate. Includes CRS summaries where available.

outsideSpending

object

FEC Schedule E data: totalFor, totalAgainst, netImpact, topCommittees

markets.polymarket

array

Active Polymarket markets mentioning this candidate, sorted by relevance

trades

array

Congressional stock trades. Empty — data pipeline in development.

revolvingDoor

array

Lobbying transitions. Empty — in development.

_meta.tier

string

Your API key's tier at time of request

Example

curl -H "Authorization: Bearer ptpk_live_YOUR_KEY" \
  "https://poltrapro.com/api/v1/candidate/ashley-moody/profile"

{
  "id": "ashley-moody",
  "name": "Ashley Moody",
  "party": "Republican",
  "finance": {
    "cycle": 2026,
    "totalRaised": 8407063,
    "totalSpent": 1277671,
    "cashOnHand": 7129392,
    "pacContributions": 1504500,
    "burnRate": 15,
    "pacShare": 18
  },
  "legislation": {
    "sponsored": [ { "billId": "S3747-119", "title": "Home School Graduation Recognition Act", ... } ],
    "sponsoredCount": 16
  },
  "outsideSpending": {
    "totalFor": 279283,
    "totalAgainst": 11675,
    "netImpact": 267608,
    "topCommittees": [ ... ]
  },
  "markets": {
    "polymarket": [
      { "question": "Will Ashley Moody be the Republican nominee?", "outcomePrices": [0.94, 0.06] }
    ]
  },
  "_meta": { "version": "1", "tier": "free" }
}

← Back to developers support@poltrapro.com