aaii.com APIaaii.com ↗
Access AAII Investor Sentiment Survey data via API. Get weekly bullish/bearish/neutral readings, ~52 weeks of history, state breakdowns, and historical averages.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/8c822fae-6fc0-4ddc-9498-e70358c72ccf/get_current_sentiment' \ -H 'X-API-Key: $PARSE_API_KEY'
Get the latest AAII investor sentiment survey data including the current week's bullish/neutral/bearish percentages, last 4 weeks of data, live vote percentages, historical averages, 1-year sentiment highs, the weekly special question with results, and the latest commentary article.
No input parameters required.
{
"type": "object",
"fields": {
"commentary": "object with date, title, url, and summary of the latest sentiment commentary article",
"current_week": "object with date, bullish, neutral, bearish percentages for the latest survey week",
"recent_weeks": "array of the last 4 weekly sentiment objects (date, bullish, neutral, bearish)",
"one_year_highs": "object with bullish_high, neutral_high, bearish_high (each containing value and week_ending)",
"special_question": "object with question, question_date, total_votes, and answers array",
"historical_averages": "object with long-term average bullish, neutral, bearish percentages",
"live_vote_percentages": "object with current live bullish, neutral, bearish vote percentages"
},
"sample": {
"data": {
"commentary": {
"url": "https://www.aaii.com/latest/article/477283-aaii-sentiment-survey-pessimism-eases",
"date": "May 7, 2026",
"title": "AAII Sentiment Survey: Pessimism Eases",
"summary": "Pessimism among individual investors about the short-term outlook for stocks decreased in the latest AAII Sentiment Survey."
},
"current_week": {
"date": "5/13/2026",
"bearish": 36.6,
"bullish": 39.3,
"neutral": 24.1
},
"recent_weeks": [
{
"date": "5/13/2026",
"bearish": 36.6,
"bullish": 39.3,
"neutral": 24.1
},
{
"date": "5/6/2026",
"bearish": 33,
"bullish": 38.3,
"neutral": 28.7
}
],
"one_year_highs": {
"bearish_high": {
"value": 52,
"week_ending": "Week Ending 3/18/2026"
},
"bullish_high": {
"value": 49.5,
"week_ending": "Week Ending 1/14/2026"
},
"neutral_high": {
"value": 31.4,
"week_ending": "Week Ending 3/4/2026"
}
},
"special_question": {
"answers": [
{
"votes": 162,
"answer": "It was the right move",
"percentage": 71.7
}
],
"question": "What do you think about the Federal Reserve's decision to keep interest rates unchanged?",
"total_votes": 226,
"question_date": "April, 30 2026 00:00:00"
},
"historical_averages": {
"bearish": 31,
"bullish": 37.5,
"neutral": 31.5
},
"live_vote_percentages": {
"bearish": 36.53,
"bullish": 39.82,
"neutral": 23.65
}
},
"status": "success"
}
}About the aaii.com API
The AAII Sentiment API provides three endpoints covering the American Association of Individual Investors' weekly survey data, which has tracked individual investor market outlook since 1987. The get_current_sentiment endpoint returns this week's bullish, neutral, and bearish percentages alongside live vote tallies, one-year highs, historical long-term averages, a weekly special question with vote results, and a link to the latest commentary article.
What the API returns
Three endpoints cover the full public surface of the AAII Investor Sentiment Survey. get_current_sentiment is the main weekly snapshot: it returns a current_week object (date, bullish, neutral, bearish percentages), a recent_weeks array of the prior four weeks, live_vote_percentages reflecting real-time voting, one_year_highs for each sentiment direction (value + week_ending date), historical_averages with long-run mean readings, and a special_question object with the current poll question, total votes, and a full answers array. A commentary object surfaces the latest editorial piece (date, title, URL, summary).
Historical and geographic data
get_historical_sentiment returns approximately 52 weeks of weekly records. Each entry in the weekly_data array includes date, bullish/neutral/bearish percentages, running bull and bear averages (bull_avg, bear_avg), and the bull-bear spread. The date_range object and total_weeks integer let you quickly verify coverage before building charts. get_state_sentiment breaks the current survey period down by US state and territory: the states object maps abbreviations (CA, TX, NY, etc.) to bullish/neutral/bearish percentages, with total_states indicating how many states have sufficient respondents for that period.
Coverage notes
All three endpoints take no input parameters — data is scoped to the current survey period or the trailing ~52-week window. The historical endpoint does not provide the full archive back to 1987 in a single call. State-level data depends on respondent counts; not every state appears every week.
- Plotting a 52-week bull-bear spread chart using the
spreadfield fromget_historical_sentiment - Alerting when bullish sentiment breaches its one-year high using
one_year_highsfromget_current_sentiment - Comparing live vote percentages against finalized weekly readings to detect intra-week sentiment shifts
- Building a regional sentiment heatmap of US states using
get_state_sentimentdata - Tracking the weekly special question results to surface topical investor concerns
- Backtesting contrarian trading signals against the historical bull-bear spread data
- Displaying the latest AAII commentary link and summary in a financial news digest via the
commentaryobject
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does AAII offer an official developer API for its sentiment data?+
What does `get_historical_sentiment` cover and how far back does it go?+
Does the state sentiment endpoint return data for every US state every week?+
get_state_sentiment endpoint only includes states and territories with sufficient survey respondents in the current period. The total_states field tells you how many are present in a given response, but low-population states may be absent in some weeks. You can fork the API on Parse and revise it to add historical state-level tracking across multiple survey periods.Can I filter historical sentiment data by a custom date range?+
get_historical_sentiment endpoint takes no input parameters and returns the trailing ~52 weeks automatically. Custom date range filtering is not currently supported. You can fork the API on Parse and revise it to add date-range query parameters against a wider historical dataset.How fresh is the data returned by `get_current_sentiment`?+
current_week object reflects the most recently published results, and live_vote_percentages reflects ongoing votes before the week closes. Intra-week live data may differ from the finalized reading published at week's end.