AAII 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.
What is the AAII 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.
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'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace aaii-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: AAII Investor Sentiment Survey — bounded, re-runnable."""
from parse_apis.aaii_investor_sentiment_survey_api import (
AAII,
SentimentUnavailable,
)
client = AAII()
# Fetch the current sentiment snapshot (single call, no pagination).
snapshot = client.sentiments.current()
print(f"Current week ({snapshot.current_week.date}): "
f"Bull {snapshot.current_week.bullish}% / "
f"Neutral {snapshot.current_week.neutral}% / "
f"Bear {snapshot.current_week.bearish}%")
# Compare live votes to the official reading.
print(f"Live votes: Bull {snapshot.live_vote_percentages.bullish}%, "
f"Bear {snapshot.live_vote_percentages.bearish}%")
# Historical averages for context.
print(f"Historical avg: Bull {snapshot.historical_averages.bullish}%, "
f"Bear {snapshot.historical_averages.bearish}%")
# Weekly special question breakdown.
sq = snapshot.special_question
print(f"Special Q: {sq.question} ({sq.total_votes} votes)")
# Fetch ~52 weeks of historical data for trend analysis.
historical = client.historicalsentiments.get()
print(f"Historical: {historical.total_weeks} weeks "
f"from {historical.date_range.start} to {historical.date_range.end}")
# Inspect the most recent week's spread.
latest = historical.weekly_data[-1]
print(f"Latest spread: {latest.spread} (bull {latest.bullish}%, bear {latest.bearish}%)")
# Fetch state-by-state sentiment; handle possible unavailability.
try:
states_report = client.statesentimentreports.get()
print(f"States reporting: {states_report.total_states}")
except SentimentUnavailable as exc:
print(f"State data unavailable: {exc}")
print("Exercised: sentiments.current / historicalsentiments.get / statesentimentreports.get")
Retrieves the latest AAII investor sentiment survey snapshot. Returns the current week's bullish/neutral/bearish percentages, the last 4 weeks of data, live vote percentages (updated in real-time as members vote), long-term historical averages, 1-year sentiment highs, the weekly special question with answer breakdown, and a link to the latest commentary article. Data refreshes each Thursday when the new survey closes.
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/493628-aaii-sentiment-survey-pessimism-steps-down",
"date": "June 4, 2026",
"title": "AAII Sentiment Survey: Pessimism Steps Down",
"summary": "Pessimism among individual investors about the short-term outlook for stocks decreased in the latest AAII Sentiment Survey."
},
"current_week": {
"date": "6/10/2026",
"bearish": 47.7,
"bullish": 30.4,
"neutral": 22
},
"recent_weeks": [
{
"date": "6/10/2026",
"bearish": 47.7,
"bullish": 30.4,
"neutral": 22
},
{
"date": "6/3/2026",
"bearish": 37,
"bullish": 36.3,
"neutral": 26.7
}
],
"one_year_highs": {
"bearish_high": {
"value": 100,
"week_ending": "Week Ending 6/11/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": 87,
"answer": "The economy and/or inflation",
"percentage": 34.8
}
],
"question": "Which factor is most influencing your six-month outlook for stocks?",
"total_votes": 250,
"question_date": "May, 28 2026 00:00:00"
},
"historical_averages": {
"bearish": 31,
"bullish": 37.5,
"neutral": 31.5
},
"live_vote_percentages": {
"bearish": 41.81,
"bullish": 33.8,
"neutral": 24.39
}
},
"status": "success"
}
}About the AAII API
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.
The AAII API is a managed, monitored endpoint for aaii.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when aaii.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official aaii.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- 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 | 100 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.