Data · API reference · version 1.0.0

API reference

Every endpoint of the data API

endpoints: 14
objects: 10

Statements

What politicians say: posts on X, press releases, newsletters and floor speeches, each with the labels the classifier gave it.

GET `/v1/statements`

Classified statements: tweets, press releases, newsletters, floor speeches (members of Congress, state legislators, governors). Tweets carry tweet_id and an empty text.

Returns up to limit items and a next_cursor; send it back as cursor, with the same other parameters, until it is null. A page that comes back full can be followed by an empty last page. Unknown parameters are refused (400).

Parameters

Parameters of GET /v1/statements
Name	In	Type	Required	Default	Description
q	query	string, up to 512 characters	no		Words; "a phrase", -not, a \| b, prefix*
sort	query	stringOne of: `relevance`, `date_desc`, `date_asc`	no		Order. Default: relevance with q, otherwise date_desc.
limit	query	integer, 1–100	no	25	Items per page.
cursor	query	string	no		next_cursor from the previous page
party	query	array of stringOne of: `D`, `R`, `I`, `O`	no		One or more values, comma-separated or repeated.
state	query	array of string	no		Two-letter state codes, e.g. PA. One or more values, comma-separated or repeated.
chamber	query	array of stringOne of: `house`, `senate`, `lower`, `upper`, `legislature`, `governor`	no		One or more values, comma-separated or repeated.
level	query	array of stringOne of: `federal`, `state`, `governor`	no		One or more values, comma-separated or repeated.
source	query	array of stringOne of: `tweets`, `tweets_state`, `tweets_governors`, `statements`, `statements_governors`, `newsletters`, `floor`, `state_floor`	no		One or more values, comma-separated or repeated.
category	query	array of stringOne of: `attack_personal`, `attack_policy`, `policy`, `bipartisanship`, `creditclaiming`	no		Kinds of statement. One or more values, comma-separated or repeated.
policy_area	query	array of string	no		Policy areas, written as the data write them. One or more values; repeat the parameter (values may contain commas).
extreme	query	stringOne of: `yes`, `no`	no		yes: only statements with an extreme label; no: only those without. yes or no (true/false and 1/0 also work).
date_from	query	string (date)	no		From this date (YYYY-MM-DD).
date_to	query	string (date)	no		Up to this date (YYYY-MM-DD).
person	query	array of string	no		Official ids: what they said. One or more values, comma-separated or repeated.
current	query	stringOne of: `yes`, `no`	no		yes or no (true/false and 1/0 also work).
year	query	string	no		Calendar year(s), e.g. 2025.

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/statements"

Response 200OK

Fields of the 200 response of GET /v1/statements
Field	Type	Description
data	array of Statement	This page.
data[].id	string	Statement id: <source>:<source id>.
data[].source	stringOne of: `tweets`, `tweets_state`, `tweets_governors`, `statements`, `statements_governors`, `newsletters`, `floor`, `state_floor`	Where it comes from. tweets, tweets_state and tweets_governors are posts on X.
data[].date	string (date)	Date.
data[].text	string	The whole text. Empty for posts on X: use tweet_id.
data[].url	string or null	The original.
data[].categories	array of stringOne of: `attack_personal`, `attack_policy`, `policy`, `bipartisanship`, `creditclaiming`	Kinds of statement the classifier found; a statement can have several or none.
data[].policy_areas	array of string	Policy areas it discusses (of 25).
data[].extreme	object or null	Set when it uses an extreme label: the label and its target.
data[].extreme.label	string	The label(s) used.
data[].extreme.target	string or null	Who or what it describes.
data[].attack	object or null	Set when it is a personal attack: the trait attacked and the target.
data[].attack.type	string or null	The trait(s) attacked.
data[].attack.target	string or null	The person attacked.
data[].person	Official	Who said it.
data[].title	string or null	Press release or newsletter subject; null for posts and floor speeches.
data[].truncated	boolean	Always false here: the API returns whole texts.
data[].tweet_id	string or null	The post's id on X (posts on X only).
next_cursor	string or null	Send it back as cursor for the next page; null on the last page.
total	integer or null	Number of matches.
meta	Meta	Licence, citation and sources, on every response.

HeadersX-RateLimit-Limit-Minute Your limit this minute. · X-RateLimit-Remaining-Minute Requests left this minute. · X-RateLimit-Limit-Day Your limit this day. · X-RateLimit-Remaining-Day Requests left this day.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/statements
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
429	Over the per-minute or per-day limit (with Retry-After)
503	Not available right now (being built, or busy); try again later

GET `/v1/statements/{id}`

One statement

Parameters

Parameters of GET /v1/statements/{id}
Name	In	Type	Required	Default	Description
id	path	string	yes		Statement id (the id field of a statement).

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/statements/$ID"

Set $ID first, and $PULSE_KEY to your key.

Response 200OK

Fields of the 200 response of GET /v1/statements/{id}
Field	Type	Description
data	Statement	A classified statement.
data.id	string	Statement id: <source>:<source id>.
data.source	stringOne of: `tweets`, `tweets_state`, `tweets_governors`, `statements`, `statements_governors`, `newsletters`, `floor`, `state_floor`	Where it comes from. tweets, tweets_state and tweets_governors are posts on X.
data.date	string (date)	Date.
data.text	string	The whole text. Empty for posts on X: use tweet_id.
data.url	string or null	The original.
data.categories	array of stringOne of: `attack_personal`, `attack_policy`, `policy`, `bipartisanship`, `creditclaiming`	Kinds of statement the classifier found; a statement can have several or none.
data.policy_areas	array of string	Policy areas it discusses (of 25).
data.extreme	object or null	Set when it uses an extreme label: the label and its target.
data.extreme.label	string	The label(s) used.
data.extreme.target	string or null	Who or what it describes.
data.attack	object or null	Set when it is a personal attack: the trait attacked and the target.
data.attack.type	string or null	The trait(s) attacked.
data.attack.target	string or null	The person attacked.
data.person	Official	Who said it.
data.title	string or null	Press release or newsletter subject; null for posts and floor speeches.
data.truncated	boolean	Always false here: the API returns whole texts.
data.tweet_id	string or null	The post's id on X (posts on X only).
next_cursor	string or null	Always null.
total	integer or null	Always null.
meta	Meta	Licence, citation and sources, on every response.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/statements/{id}
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
404	Not found
429	Over the per-minute or per-day limit (with Retry-After)
503	Not available right now (being built, or busy); try again later

Officials

Members of Congress, state legislators and governors, with full profiles and roll-call records.

GET `/v1/officials`

Officials: members of Congress, state legislators, governors.

Parameters

Parameters of GET /v1/officials
Name	In	Type	Required	Default	Description
q	query	string, up to 512 characters	no		Words; "a phrase", -not, a \| b, prefix*
sort	query	stringOne of: `relevance`, `name`, `csip_asc`, `csip_desc`, `statements_desc`, `extreme_desc`	no		Order. Default: relevance with q, otherwise name.
limit	query	integer, 1–100	no	25	Items per page.
cursor	query	string	no		next_cursor from the previous page
party	query	array of stringOne of: `D`, `R`, `I`, `O`	no		One or more values, comma-separated or repeated.
state	query	array of string	no		Two-letter state codes, e.g. PA. One or more values, comma-separated or repeated.
chamber	query	array of stringOne of: `house`, `senate`, `lower`, `upper`, `legislature`, `governor`	no		One or more values, comma-separated or repeated.
level	query	array of stringOne of: `federal`, `state`, `governor`	no		One or more values, comma-separated or repeated.
csip_min	query	number	no		Ideology (CSIP) score. At least this number.
csip_max	query	number	no		Ideology (CSIP) score. At most this number.

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/officials"

Response 200OK

Fields of the 200 response of GET /v1/officials
Field	Type	Description
data	array of Official	This page.
data[].id	string	Official id: the bioguide id (Congress), the Open States id without ocd-person/ (state legislators) or gov-<slug> (governors). Use it with /v1/officials/{id}.
data[].level	stringOne of: `federal`, `state`, `governor`	Level of government.
data[].name	string	Name.
data[].party	stringOne of: `D`, `R`, `I`, `O`	Party; O is any other, or none.
data[].state	string	State, as a two-letter code.
data[].chamber	stringOne of: `house`, `senate`, `lower`, `upper`, `legislature`, `governor`	Chamber or office.
data[].district	string or null	District, where the seat has one.
data[].photo	string or null	Photo: a site-relative or full URL.
data[].csip	number or null	Ideology (CSIP) from the latest validated run. 0 is the centre of the scale; negative is more liberal, positive more conservative.
data[].statements	integer	Statements in the current window.
data[].extremeRate	number or null	Share of statements with an extreme label, current window (0 to 1).
next_cursor	string or null	Send it back as cursor for the next page; null on the last page.
total	integer or null	Number of matches.
meta	Meta	Licence, citation and sources, on every response.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/officials
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
429	Over the per-minute or per-day limit (with Retry-After)
503	Not available right now (being built, or busy); try again later

GET `/v1/officials/{id}`

An official's full profile (rhetoric, policy, ideology, money, votes, legislation)

Tweet text is removed everywhere in the profile, as in every response.

Parameters

Parameters of GET /v1/officials/{id}
Name	In	Type	Required	Default	Description
id	path	string	yes		Official id (the id field of an official).

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/officials/$ID"

Set $ID first, and $PULSE_KEY to your key.

Response 200OK

Fields of the 200 response of GET /v1/officials/{id}
Field	Type	Description
data	object	The profile, as the site's profile page uses it.
next_cursor	string or null	Always null.
total	integer or null	Always null.
meta	Meta	Licence, citation and sources, on every response.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/officials/{id}
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
404	Not found
429	Over the per-minute or per-day limit (with Retry-After)

GET `/v1/officials/{id}/votes`

An official's roll-call votes, newest first

One page is one stored part of the record; follow next_cursor to the end. Records are written for term windows (current and term:<id>) only, so 12m and all find nothing (404).

Parameters

Parameters of GET /v1/officials/{id}/votes
Name	In	Type	Required	Default	Description
id	path	string	yes		Official id.
window	query	string	no	current	current, 12m, all or term:<id>
cursor	query	string	no		next_cursor from the previous page

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/officials/$ID/votes"

Set $ID first, and $PULSE_KEY to your key.

Response 200OK

Fields of the 200 response of GET /v1/officials/{id}/votes
Field	Type	Description
data	array of OfficialVote	This page.
data[].vote_id	string	Roll-call id; federal ids are us-<congress>-<h\|s>-<roll>.
data[].date	string (date)	Date of the vote.
data[].chamber	stringOne of: `house`, `senate`, `lower`, `upper`, `legislature`, `governor`	Chamber.
data[].bill	string or null	The bill voted on, if any.
data[].bill_title	string or null	Its title.
data[].question	string	The question put to the vote.
data[].result	string	The result, as recorded.
data[].margin	number or null	Margin of the result (smaller is closer).
data[].party_split	object	Yeas and nays by party (D, R, I, O).
data[].party_split.<key>.yea	integer	Yeas.
data[].party_split.<key>.nay	integer	Nays.
data[].key_reasons	array of stringOne of: `law`, `close`, `crossover`, `salient`	Why it is a key vote: law (became law), close (decided by under 10%), crossover (at least 10% of a party voted against its majority), salient (one of the 25 bills officials mention most).
data[].url	string or null	The roll call at its source.
data[].position	stringOne of: `yea`, `nay`, `present`, `not_voting`	How the official voted.
data[].with_party	boolean or null	Whether the vote was with the majority of the official's party.
next_cursor	string or null	Send it back as cursor for the next page; null on the last page.
total	integer or null	Always null.
meta	Meta	Licence, citation and sources, on every response.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/officials/{id}/votes
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
404	Not found
429	Over the per-minute or per-day limit (with Retry-After)

Bills

Federal and state bills, and the same proposal in other states.

GET `/v1/bills`

Federal and state bills with sponsors, stage and policy area.

Parameters

Parameters of GET /v1/bills
Name	In	Type	Required	Default	Description
q	query	string, up to 512 characters	no		Words; "a phrase", -not, a \| b, prefix*
sort	query	stringOne of: `relevance`, `date_desc`, `date_asc`, `latest_desc`	no		Order. Default: relevance with q, otherwise date_desc.
limit	query	integer, 1–100	no	25	Items per page.
cursor	query	string	no		next_cursor from the previous page
jurisdiction	query	array of string	no		US for Congress, or two-letter state codes. One or more values, comma-separated or repeated.
session	query	array of string	no		One or more values, comma-separated or repeated.
policy_area	query	array of string	no		Policy areas, written as the data write them. One or more values; repeat the parameter (values may contain commas).
status	query	array of stringOne of: `introduced`, `committee`, `passed_one`, `passed_both`, `law`	no		One or more values, comma-separated or repeated.
sponsor	query	array of string	no		Official id: bills they sponsored or cosponsored.
date_from	query	string (date)	no		From this date (YYYY-MM-DD).
date_to	query	string (date)	no		Up to this date (YYYY-MM-DD).

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/bills"

Response 200OK

Fields of the 200 response of GET /v1/bills
Field	Type	Description
data	array of Bill	This page.
data[].bill_id	string	Bill id.
data[].jurisdiction	string	US for Congress, or a state's two-letter code.
data[].session	string	Session.
data[].number	string	Bill number.
data[].title	string	Title.
data[].introduced	string (date) or null	Date introduced.
data[].status	stringOne of: `introduced`, `committee`, `passed_one`, `passed_both`, `law`	The furthest stage reached.
data[].latest_action	string or null	The latest action.
data[].latest_action_date	string (date) or null	Its date.
data[].policy_area	string or null	Policy area (of 25).
data[].policy_area_source	string or nullOne of: `crs`, `llm`	crs when the Congressional Research Service assigned the area, llm when a language model did.
data[].policy_area_crs	string or null	Federal only: the CRS policy area (of 33) before it is mapped to the 25.
data[].url	string or null	The bill at its source.
data[].sponsors	array of Official	Sponsors.
data[].n_cosponsors	integer	Number of cosponsors.
next_cursor	string or null	Send it back as cursor for the next page; null on the last page.
total	integer or null	Number of matches.
meta	Meta	Licence, citation and sources, on every response.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/bills
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
429	Over the per-minute or per-day limit (with Retry-After)
503	Not available right now (being built, or busy); try again later

GET `/v1/bills/{bill_id}/similar`

The same proposal in other states (similarity 0.87 or more)

Only state bills are compared; total is the number of similar bills.

Parameters

Parameters of GET /v1/bills/{bill_id}/similar
Name	In	Type	Required	Default	Description
bill_id	path	string	yes		A state bill's id (the bill_id field of a bill).

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/bills/$BILL_ID/similar"

Set $BILL_ID first, and $PULSE_KEY to your key.

Response 200OK

Fields of the 200 response of GET /v1/bills/{bill_id}/similar
Field	Type	Description
data	SimilarBills
data.bill	object	The bill asked about.
data.bill.bill_id	string	Bill id.
data.bill.jurisdiction	string	State, as a two-letter code.
data.bill.number	string	Bill number.
data.bill.year	integer or null	Year.
data.bill.title	string	Title.
data.bill.became_law	boolean	Whether it became law.
data.threshold	number	The similarity a bill needs to count as the same.
data.similar	array of object	The same proposal in other states.
data.similar[].bill_id	string	Bill id.
data.similar[].jurisdiction	string	State, as a two-letter code.
data.similar[].number	string	Bill number.
data.similar[].year	integer or null	Year.
data.similar[].title	string	Title.
data.similar[].became_law	boolean	Whether it became law.
data.similar[].similarity	number	Cosine similarity of the two texts.
next_cursor	string or null	Always null.
total	integer or null	Number of items.
meta	Meta	Licence, citation and sources, on every response.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/bills/{bill_id}/similar
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
404	Not found
429	Over the per-minute or per-day limit (with Retry-After)
503	Not available right now (being built, or busy); try again later

Votes

Roll-call votes with party splits.

GET `/v1/votes`

Roll-call votes with party splits.

Parameters

Parameters of GET /v1/votes
Name	In	Type	Required	Default	Description
q	query	string, up to 512 characters	no		Words; "a phrase", -not, a \| b, prefix*
sort	query	stringOne of: `relevance`, `date_desc`, `date_asc`, `margin_asc`	no		Order. Default: relevance with q, otherwise date_desc.
limit	query	integer, 1–100	no	25	Items per page.
cursor	query	string	no		next_cursor from the previous page
jurisdiction	query	array of string	no		US for Congress, or two-letter state codes. One or more values, comma-separated or repeated.
chamber	query	array of stringOne of: `house`, `senate`, `lower`, `upper`, `legislature`, `governor`	no		One or more values, comma-separated or repeated.
date_from	query	string (date)	no		From this date (YYYY-MM-DD).
date_to	query	string (date)	no		Up to this date (YYYY-MM-DD).
key	query	stringOne of: `yes`, `no`	no		yes: only key votes; no: only the others. yes or no (true/false and 1/0 also work).
bill	query	array of string	no		One or more values, comma-separated or repeated.
floor	query	stringOne of: `yes`, `no`	no		yes or no (true/false and 1/0 also work).
result	query	array of string	no		One or more values; repeat the parameter (values may contain commas).
year	query	string	no		Calendar year(s), e.g. 2025.

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/votes"

Response 200OK

Fields of the 200 response of GET /v1/votes
Field	Type	Description
data	array of Vote	This page.
data[].vote_id	string	Roll-call id; federal ids are us-<congress>-<h\|s>-<roll>.
data[].date	string (date)	Date of the vote.
data[].chamber	stringOne of: `house`, `senate`, `lower`, `upper`, `legislature`, `governor`	Chamber.
data[].bill	string or null	The bill voted on, if any.
data[].bill_title	string or null	Its title.
data[].question	string	The question put to the vote.
data[].result	string	The result, as recorded.
data[].margin	number or null	Margin of the result (smaller is closer).
data[].party_split	object	Yeas and nays by party (D, R, I, O).
data[].party_split.<key>.yea	integer	Yeas.
data[].party_split.<key>.nay	integer	Nays.
data[].key_reasons	array of stringOne of: `law`, `close`, `crossover`, `salient`	Why it is a key vote: law (became law), close (decided by under 10%), crossover (at least 10% of a party voted against its majority), salient (one of the 25 bills officials mention most).
data[].url	string or null	The roll call at its source.
data[].jurisdiction	string	US, or a state's two-letter code.
data[].yea	integer or null	Yeas.
data[].nay	integer or null	Nays.
data[].key	boolean	Whether it is a key vote.
next_cursor	string or null	Send it back as cursor for the next page; null on the last page.
total	integer or null	Number of matches.
meta	Meta	Licence, citation and sources, on every response.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/votes
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
429	Over the per-minute or per-day limit (with Retry-After)
503	Not available right now (being built, or busy); try again later

Surveys

Aggregates from the America's Political Pulse survey. Never individual responses.

GET `/v1/surveys/state-estimates`

State opinion estimates (MRP)

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/surveys/state-estimates"

Response 200OK

Fields of the 200 response of GET /v1/surveys/state-estimates
Field	Type	Description
data	any	The published file, as the site uses it.
next_cursor	string or null	Always null.
total	integer or null	Always null.
meta	Meta	Licence, citation and sources, on every response.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/surveys/state-estimates
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
429	Over the per-minute or per-day limit (with Retry-After)
503	Not available right now (being built, or busy); try again later

GET `/v1/surveys/toplines`

Survey topline reports

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/surveys/toplines"

Response 200OK

Fields of the 200 response of GET /v1/surveys/toplines
Field	Type	Description
data	any	The published file, as the site uses it.
next_cursor	string or null	Always null.
total	integer or null	Always null.
meta	Meta	Licence, citation and sources, on every response.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/surveys/toplines
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
429	Over the per-minute or per-day limit (with Retry-After)
503	Not available right now (being built, or busy); try again later

Political violence

Political violence events in the United States.

GET `/v1/violence/events`

Political violence events

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/violence/events"

Response 200OK

Fields of the 200 response of GET /v1/violence/events
Field	Type	Description
data	any	The published file, as the site uses it.
next_cursor	string or null	Always null.
total	integer or null	Always null.
meta	Meta	Licence, citation and sources, on every response.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/violence/events
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
429	Over the per-minute or per-day limit (with Retry-After)
503	Not available right now (being built, or busy); try again later

Bulk files

Whole datasets, zipped CSV and Parquet.

GET `/v1/bulk`

Bulk files (CSV and Parquet zips)

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/bulk"

Response 200OK

Fields of the 200 response of GET /v1/bulk
Field	Type	Description
data	array of BulkFile	Every bulk file.
data[].name	string	Name, for /v1/bulk/{name}.
data[].description	string	What the file holds.
data[].rows	integer	Rows.
data[].bytes	integer	Size of the zip.
data[].formats	array of string	Formats in the zip.
data[].download	string	Where to download it.
next_cursor	string or null	Always null.
total	integer or null	Number of items.
meta	Meta	Licence, citation and sources, on every response.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/bulk
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
429	Over the per-minute or per-day limit (with Retry-After)
503	Not available right now (being built, or busy); try again later

GET `/v1/bulk/{name}`

Download a bulk file (302 to a five-minute link; counts toward the daily downloads)

Parameters

Parameters of GET /v1/bulk/{name}
Name	In	Type	Required	Default	Description
name	path	string	yes		The file's name, from /v1/bulk.

Example request

curl -L -OJ -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/bulk/$NAME"

Set $NAME first, and $PULSE_KEY to your key.

Response 302Redirect to the file

HeadersLocation A download link, valid for five minutes. · X-RateLimit-Limit-Minute Your limit this minute. · X-RateLimit-Remaining-Minute Requests left this minute. · X-RateLimit-Limit-Day Your limit this day. · X-RateLimit-Remaining-Day Requests left this day.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/bulk/{name}
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
404	Not found
429	Over a rate limit (see Retry-After), or today's downloads are used up (they reset at midnight UTC)

Account

Your own limits and use.

GET `/v1/usage`

Your limits and use

Example request

curl -H "Authorization: Bearer $PULSE_KEY" \
  "https://api.americaspoliticalpulse.com/v1/usage"

Response 200OK

Fields of the 200 response of GET /v1/usage
Field	Type	Description
data	Usage
data.limits	object	Your account's limits.
data.limits.requests_per_minute	integer	Per minute.
data.limits.requests_per_day	integer	Per day (UTC).
data.limits.downloads_per_day	integer	Bulk downloads per day (UTC).
data.today	object
data.today.requests	integer	Requests today (UTC).
data.today.by_resource	object	Requests today by resource (statements, officials, …).
data.days	array of object	The last 30 days with requests.
data.days[].date	string	Day, as YYYYMMDD (UTC).
data.days[].requests	integer	Requests that day.
next_cursor	string or null	Always null.
total	integer or null	Always null.
meta	Meta	Licence, citation and sources, on every response.

Errors

Each comes as Error: {"error": "…"}.

Errors of GET /v1/usage
Status	When
400	A parameter is wrong (the message says which), or the key was sent in the URL
401	No key, or a key that is not valid (revoked or mistyped)
403	The account is suspended, or the API is not open to it yet
429	Over the per-minute or per-day limit (with Retry-After)

Objects

The objects the endpoints return, each described once. A type in a table that names one links here.

Fields of Meta
Field	Type	Description
licence	string	The data licence (CC BY 4.0).
licence_url	string	The licence text.
citation	string	How to cite the data.
sources	string	The outside sources behind the data, with their terms and the credit each asks for.
docs	string	This API's guide.
as_of	string	When the data were built, where the resource records it.

Error

The body of every error response.

Fields of Error
Field	Type	Description
error	string	What went wrong, in plain words.

Official

An official, as lists show them.

Fields of Official
Field	Type	Description
id	string	Official id: the bioguide id (Congress), the Open States id without ocd-person/ (state legislators) or gov-<slug> (governors). Use it with /v1/officials/{id}.
level	stringOne of: `federal`, `state`, `governor`	Level of government.
name	string	Name.
party	stringOne of: `D`, `R`, `I`, `O`	Party; O is any other, or none.
state	string	State, as a two-letter code.
chamber	stringOne of: `house`, `senate`, `lower`, `upper`, `legislature`, `governor`	Chamber or office.
district	string or null	District, where the seat has one.
photo	string or null	Photo: a site-relative or full URL.
csip	number or null	Ideology (CSIP) from the latest validated run. 0 is the centre of the scale; negative is more liberal, positive more conservative.
statements	integer	Statements in the current window.
extremeRate	number or null	Share of statements with an extreme label, current window (0 to 1).

Statement

A classified statement.

Fields of Statement
Field	Type	Description
id	string	Statement id: <source>:<source id>.
source	stringOne of: `tweets`, `tweets_state`, `tweets_governors`, `statements`, `statements_governors`, `newsletters`, `floor`, `state_floor`	Where it comes from. tweets, tweets_state and tweets_governors are posts on X.
date	string (date)	Date.
text	string	The whole text. Empty for posts on X: use tweet_id.
url	string or null	The original.
categories	array of stringOne of: `attack_personal`, `attack_policy`, `policy`, `bipartisanship`, `creditclaiming`	Kinds of statement the classifier found; a statement can have several or none.
policy_areas	array of string	Policy areas it discusses (of 25).
extreme	object or null	Set when it uses an extreme label: the label and its target.
extreme.label	string	The label(s) used.
extreme.target	string or null	Who or what it describes.
attack	object or null	Set when it is a personal attack: the trait attacked and the target.
attack.type	string or null	The trait(s) attacked.
attack.target	string or null	The person attacked.
person	Official	Who said it.
title	string or null	Press release or newsletter subject; null for posts and floor speeches.
truncated	boolean	Always false here: the API returns whole texts.
tweet_id	string or null	The post's id on X (posts on X only).

Bill

A bill.

Fields of Bill
Field	Type	Description
bill_id	string	Bill id.
jurisdiction	string	US for Congress, or a state's two-letter code.
session	string	Session.
number	string	Bill number.
title	string	Title.
introduced	string (date) or null	Date introduced.
status	stringOne of: `introduced`, `committee`, `passed_one`, `passed_both`, `law`	The furthest stage reached.
latest_action	string or null	The latest action.
latest_action_date	string (date) or null	Its date.
policy_area	string or null	Policy area (of 25).
policy_area_source	string or nullOne of: `crs`, `llm`	crs when the Congressional Research Service assigned the area, llm when a language model did.
policy_area_crs	string or null	Federal only: the CRS policy area (of 33) before it is mapped to the 25.
url	string or null	The bill at its source.
sponsors	array of Official	Sponsors.
n_cosponsors	integer	Number of cosponsors.

Vote

A roll-call vote.

Fields of Vote
Field	Type	Description
vote_id	string	Roll-call id; federal ids are us-<congress>-<h\|s>-<roll>.
date	string (date)	Date of the vote.
chamber	stringOne of: `house`, `senate`, `lower`, `upper`, `legislature`, `governor`	Chamber.
bill	string or null	The bill voted on, if any.
bill_title	string or null	Its title.
question	string	The question put to the vote.
result	string	The result, as recorded.
margin	number or null	Margin of the result (smaller is closer).
party_split	object	Yeas and nays by party (D, R, I, O).
party_split.<key>.yea	integer	Yeas.
party_split.<key>.nay	integer	Nays.
key_reasons	array of stringOne of: `law`, `close`, `crossover`, `salient`	Why it is a key vote: law (became law), close (decided by under 10%), crossover (at least 10% of a party voted against its majority), salient (one of the 25 bills officials mention most).
url	string or null	The roll call at its source.
jurisdiction	string	US, or a state's two-letter code.
yea	integer or null	Yeas.
nay	integer or null	Nays.
key	boolean	Whether it is a key vote.

OfficialVote

A roll call, with how one official voted.

Fields of OfficialVote
Field	Type	Description
vote_id	string	Roll-call id; federal ids are us-<congress>-<h\|s>-<roll>.
date	string (date)	Date of the vote.
chamber	stringOne of: `house`, `senate`, `lower`, `upper`, `legislature`, `governor`	Chamber.
bill	string or null	The bill voted on, if any.
bill_title	string or null	Its title.
question	string	The question put to the vote.
result	string	The result, as recorded.
margin	number or null	Margin of the result (smaller is closer).
party_split	object	Yeas and nays by party (D, R, I, O).
party_split.<key>.yea	integer	Yeas.
party_split.<key>.nay	integer	Nays.
key_reasons	array of stringOne of: `law`, `close`, `crossover`, `salient`	Why it is a key vote: law (became law), close (decided by under 10%), crossover (at least 10% of a party voted against its majority), salient (one of the 25 bills officials mention most).
url	string or null	The roll call at its source.
position	stringOne of: `yea`, `nay`, `present`, `not_voting`	How the official voted.
with_party	boolean or null	Whether the vote was with the majority of the official's party.

SimilarBills

Fields of SimilarBills
Field	Type	Description
bill	object	The bill asked about.
bill.bill_id	string	Bill id.
bill.jurisdiction	string	State, as a two-letter code.
bill.number	string	Bill number.
bill.year	integer or null	Year.
bill.title	string	Title.
bill.became_law	boolean	Whether it became law.
threshold	number	The similarity a bill needs to count as the same.
similar	array of object	The same proposal in other states.
similar[].bill_id	string	Bill id.
similar[].jurisdiction	string	State, as a two-letter code.
similar[].number	string	Bill number.
similar[].year	integer or null	Year.
similar[].title	string	Title.
similar[].became_law	boolean	Whether it became law.
similar[].similarity	number	Cosine similarity of the two texts.

BulkFile

A bulk file (further fields come from the files' manifest).

Fields of BulkFile
Field	Type	Description
name	string	Name, for /v1/bulk/{name}.
description	string	What the file holds.
rows	integer	Rows.
bytes	integer	Size of the zip.
formats	array of string	Formats in the zip.
download	string	Where to download it.

Usage

Fields of Usage
Field	Type	Description
limits	object	Your account's limits.
limits.requests_per_minute	integer	Per minute.
limits.requests_per_day	integer	Per day (UTC).
limits.downloads_per_day	integer	Bulk downloads per day (UTC).
today	object
today.requests	integer	Requests today (UTC).
today.by_resource	object	Requests today by resource (statements, officials, …).
days	array of object	The last 30 days with requests.
days[].date	string	Day, as YYYYMMDD (UTC).
days[].requests	integer	Requests that day.

Statements

GET /v1/statements

Parameters

Example request

Response 200OK

Errors

GET /v1/statements/{id}

Parameters

Example request

Response 200OK

Errors

Officials

GET /v1/officials

Parameters

Example request

Response 200OK

Errors

GET /v1/officials/{id}

Parameters

Example request

Response 200OK

Errors

GET /v1/officials/{id}/votes

Parameters

Example request

Response 200OK

Errors

Bills

GET /v1/bills

Parameters

Example request

Response 200OK

Errors

GET /v1/bills/{bill_id}/similar

Parameters

Example request

Response 200OK

Errors

Votes

GET /v1/votes

Parameters

Example request

Response 200OK

Errors

Surveys

GET /v1/surveys/state-estimates

Example request

Response 200OK

Errors

GET /v1/surveys/toplines

Example request

Response 200OK

Errors

Political violence

GET /v1/violence/events

Example request

Response 200OK

Errors

Bulk files

GET /v1/bulk

Example request

Response 200OK

Errors

GET /v1/bulk/{name}

Parameters

Example request

Response 302Redirect to the file

Errors

Account

GET /v1/usage

Example request

Response 200OK

Errors

Objects

Meta

Error

Official

Statement

Bill

Vote

GET `/v1/statements`

GET `/v1/statements/{id}`

GET `/v1/officials`

GET `/v1/officials/{id}`

GET `/v1/officials/{id}/votes`

GET `/v1/bills`

GET `/v1/bills/{bill_id}/similar`

GET `/v1/votes`

GET `/v1/surveys/state-estimates`

GET `/v1/surveys/toplines`

GET `/v1/violence/events`

GET `/v1/bulk`

GET `/v1/bulk/{name}`

GET `/v1/usage`