You've built Streamlit dashboards before, perhaps even dabbled with @st.cache_data. But if you’ve ever found your "real-time" dashboard sluggish, inexplicably losing user selections, or constantly hammering an external API, you know the frustration. The naive approach to Streamlit often falls short when confronted with volatile external REST endpoints and the demand for a truly interactive, production-grade experience. This post is for senior data engineers and developers who need to move beyond basic Streamlit patterns. I’ll walk you through how to architect reactive, resilient dashboards that maintain state consistency, handle API rate limits gracefully, and update granular UI components using fragments, all while consuming a dynamic API feed.
Key Takeaways
- How to decouple expensive external API calls from UI re-renders using
@st.cache_datawith precise TTLs. - Managing multi-step user interaction filters and persistent selections using
st.session_state. - Leveraging
@st.fragmentto update sub-components asynchronously without triggering full-page reruns. - Implementing robust exponential backoff and error recovery when consuming public REST endpoints in production UI loops.
The Problem
We need to build an analytical dashboard that visualizes demographic data from a volatile external REST API. The challenges are clear: frequent API calls can lead to rate limiting, network instability causes UI blocking, and every user interaction often triggers a full page rerun, wiping out previous selections and re-fetching data unnecessarily. Our goal is to create a dashboard that feels fast, remembers user choices, and updates only the necessary components, even when the underlying data source is dynamic and potentially unreliable.
Data and Sources
We'll be using the Random User API to simulate a dynamic external data source. This API provides randomly generated user data, perfect for demonstrating data fetching, normalization, and filtering. We'll specifically request a batch of user profiles including gender, name, location, email, and nationality.
- Random User API Documentation: https://randomuser.me/documentation
- Streamlit Caching & State Management Reference: https://docs.streamlit.io/
Data accessed on 2024-07-30.
Step 1 — Resilient Data Fetching with Backoff
How do we consume unstable external feeds without breaking the UI thread? Public APIs are not always 100% reliable. Network glitches, temporary server overloads, or intermittent rate limiting can cause your dashboard to fail or, worse, become unresponsive. Simply calling requests.get() is asking for trouble in production. I learned to wrap these calls with a robust retry mechanism, specifically using the tenacity library for exponential backoff.
Here, I define a decorator that retries API calls with increasing delays. This prevents us from overwhelming the API with immediate retries and gives the service time to recover. It also handles common network errors gracefully, ensuring our data fetching function doesn't crash the entire Streamlit app on the first hiccup.
import requests
import pandas as pd
import streamlit as st
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
@retry(
stop=stop_after_attempt(5),
wait=wait_exponential(multiplier=1, min=4, max=10),
retry=retry_if_exception_type(requests.exceptions.RequestException),
reraise=True
)
def _fetch_random_users(num_results: int = 50) -> dict:
"""
Fetches random user data from the Random User API with retry logic.
"""
api_url = f"https://randomuser.me/api/?results={num_results}&inc=gender,name,location,email,nat"
try:
response = requests.get(api_url, timeout=10)
response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
return response.json()
except requests.exceptions.RequestException as e:
st.error(f"API Request failed: {e}. Retrying...")
raise # Re-raise to trigger tenacity retry
The _fetch_random_users function now attempts to fetch data up to 5 times. It waits exponentially between retries (starting at 4 seconds, up to 10), specifically for requests.exceptions.RequestException, which covers network issues, timeouts, and HTTP errors. This significantly improves the resilience of our data ingestion.
Step 2 — Advanced Caching and TTL Strategies
How do we prevent redundant network I/O during user filter adjustments? Once we have resilient data fetching, the next challenge is ensuring we don't refetch data unnecessarily. Streamlit's @st.cache_data is powerful, but a simple application might still refetch if the input arguments change, or if you need data to be periodically fresh without constant manual intervention. For external APIs, we need a Time-To-Live (TTL) strategy.
By specifying ttl=60, I tell Streamlit to re-run the fetch_and_normalize_data function only if 60 seconds have passed since the last successful run or if its input arguments change. This means user interactions like filtering, which don't change the API call parameters, won't trigger a refetch. The show_spinner argument provides crucial user feedback during the initial load or a cache refresh, preventing the UI from appearing frozen.
@st.cache_data(ttl=60, show_spinner="Fetching fresh demographic data...")
def fetch_and_normalize_data(num_results: int = 100) -> pd.DataFrame:
"""
Fetches user data and normalizes it into a flat Pandas DataFrame.
Cached with a TTL to prevent frequent API calls.
"""
raw_data = _fetch_random_users(num_results)
users = raw_data.get('results', [])
if not users:
return pd.DataFrame()
df = pd.json_normalize(users)
# Flatten nested location data for easier filtering
df['city'] = df['location.city']
df['state'] = df['location.state']
df['country'] = df['location.country']
df['nat'] = df['nat'] # Nationality code
# Select and rename relevant columns
df = df[['gender', 'name.first', 'name.last', 'email', 'city', 'state', 'country', 'nat']]
df.columns = ['Gender', 'First Name', 'Last Name', 'Email', 'City', 'State', 'Country', 'Nationality']
return df
This function now acts as our single source of truth for the raw data, ensuring it's fresh enough for our needs but not over-fetched. The normalization step flattens the nested JSON structure into a clean Pandas DataFrame, making it ready for filtering and visualization.
Step 3 — Stateful UI Filtering and Session Management
How do we retain user search criteria across widget redraws? Streamlit's rerun model can be tricky. Every time a widget value changes, the script reruns from top to bottom. Without proper state management, any filter selections or user inputs would be lost. This is where st.session_state becomes indispensable. It's a dictionary-like object that persists across reruns, allowing us to store and retrieve user-specific data.
I initialize default values in st.session_state for our filters if they don't already exist. This ensures that the dashboard starts with sensible defaults and that previous selections are preserved. I then bind st.multiselect and st.slider widgets to these session state keys. When a user changes a filter, the value is automatically updated in st.session_state, and the next rerun will use this stored value to re-filter the DataFrame, maintaining a consistent user experience.
def initialize_session_state(df: pd.DataFrame):
if 'selected_countries' not in st.session_state:
st.session_state.selected_countries = df['Country'].unique().tolist()
if 'selected_genders' not in st.session_state:
st.session_state.selected_genders = df['Gender'].unique().tolist()
if 'min_users_per_country' not in st.session_state:
st.session_state.min_users_per_country = 1
def apply_filters(df: pd.DataFrame) -> pd.DataFrame:
st.sidebar.header("Filter Data")
all_countries = df['Country'].unique().tolist()
st.session_state.selected_countries = st.sidebar.multiselect(
"Select Countries",
options=all_countries,
default=st.session_state.selected_countries,
key="country_filter"
)
all_genders = df['Gender'].unique().tolist()
st.session_state.selected_genders = st.sidebar.multiselect(
"Select Genders",
options=all_genders,
default=st.session_state.selected_genders,
key="gender_filter"
)
# Filter by selected countries and genders
filtered_df = df[
(df['Country'].isin(st.session_state.selected_countries)) &
(df['Gender'].isin(st.session_state.selected_genders))
]
return filtered_df
This approach makes our dashboard interactive without losing context. User selections persist, providing a much smoother experience. Notice how the `key` argument is used in the `st.multiselect` to ensure Streamlit correctly tracks the widget's state.
Step 4 — Fragment Rendering for Targeted Updates
How do we optimize dashboard render performance for high-frequency metrics? Even with caching and session state, a full page rerun for small, frequently updated components can be inefficient. Imagine a dashboard with real-time counters or status indicators. Rerunning the entire script just to update these can lead to UI flickering and wasted computation. Streamlit's @st.fragment decorator is the answer to this problem.
A fragment is a self-contained block of Streamlit code that can be rerun independently of the main script. By decorating a function with @st.fragment(run_every=5), I instruct Streamlit to execute and re-render only that specific part of the UI every 5 seconds, without affecting the rest of the page. This is incredibly powerful for displaying "live" metrics or data summaries that need frequent updates without disrupting other user interactions or heavy computations elsewhere on the page.
import matplotlib.pyplot as plt
import io
@st.fragment(run_every=5)
def display_realtime_metrics(df: pd.DataFrame):
"""
Displays real-time metrics, updated every 5 seconds using st.fragment.
"""
st.subheader("Real-time Metrics (Updates every 5s)")
col1, col2, col3 = st.columns(3)
with col1:
st.metric(label="Total Users", value=f"{len(df):,}")
with col2:
st.metric(label="Unique Countries", value=f"{df['Country'].nunique():,}")
with col3:
st.metric(label="Avg Users per Country", value=f"{len(df) / df['Country'].nunique():.1f}")
# Example plot for gender distribution
gender_counts = df['Gender'].value_counts()
fig, ax = plt.subplots(figsize=(4, 2))
gender_counts.plot(kind='bar', ax=ax, color=['skyblue', 'lightcoral'])
ax.set_title('Gender Distribution', fontsize=8)
ax.set_ylabel('Count', fontsize=6)
ax.tick_params(axis='both', which='major', labelsize=6)
plt.tight_layout()
st.pyplot(fig) # This will display the plot in the fragment
plt.close(fig) # Close the figure to free up memory
In this fragment, I'm displaying summary statistics and a simple gender distribution plot. Because it's a fragment, these metrics will automatically refresh every 5 seconds, giving the user a sense of dynamism without impacting the performance of the main dashboard, especially if they are busy interacting with filters or viewing a large data table.
Complete Script
The full runnable script combining all steps:
#!/usr/bin/env python3
import requests
import pandas as pd
import streamlit as st
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
import matplotlib.pyplot as plt
import io # Required for saving plot to buffer if needed, though st.pyplot handles it directly
# --- Step 1: Resilient Data Fetching with Backoff ---
@retry(
stop=stop_after_attempt(5),
wait=wait_exponential(multiplier=1, min=4, max=10),
retry=retry_if_exception_type(requests.exceptions.RequestException),
reraise=True
)
def _fetch_random_users(num_results: int = 100) -> dict:
"""
Fetches random user data from the Random User API with retry logic.
"""
api_url = f"https://randomuser.me/api/?results={num_results}&inc=gender,name,location,email,nat"
try:
response = requests.get(api_url, timeout=10)
response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
return response.json()
except requests.exceptions.RequestException as e:
st.error(f"API Request failed: {e}. Retrying...")
raise # Re-raise to trigger tenacity retry
# --- Step 2: Advanced Caching and TTL Strategies ---
@st.cache_data(ttl=60, show_spinner="Fetching fresh demographic data...")
def fetch_and_normalize_data(num_results: int = 100) -> pd.DataFrame:
"""
Fetches user data and normalizes it into a flat Pandas DataFrame.
Cached with a TTL to prevent frequent API calls.
"""
try:
raw_data = _fetch_random_users(num_results)
except requests.exceptions.RequestException:
st.error("Failed to fetch data after multiple retries. Please try again later.")
return pd.DataFrame() # Return empty DataFrame on persistent failure
users = raw_data.get('results', [])
if not users:
return pd.DataFrame()
df = pd.json_normalize(users)
# Flatten nested location data for easier filtering
df['city'] = df['location.city']
df['state'] = df['location.state']
df['country'] = df['location.country']
df['nat'] = df['nat'] # Nationality code
# Select and rename relevant columns
df = df[['gender', 'name.first', 'name.last', 'email', 'city', 'state', 'country', 'nat']]
df.columns = ['Gender', 'First Name', 'Last Name', 'Email', 'City', 'State', 'Country', 'Nationality']
return df
# --- Step 3: Stateful UI Filtering and Session Management ---
def initialize_session_state(df: pd.DataFrame):
"""Initializes session state variables for filters if they don't exist."""
if 'selected_countries' not in st.session_state:
st.session_state.selected_countries = df['Country'].unique().tolist()
if 'selected_genders' not in st.session_state:
st.session_state.selected_genders = df['Gender'].unique().tolist()
def apply_filters(df: pd.DataFrame) -> pd.DataFrame:
"""Applies filters based on user selections in the sidebar."""
st.sidebar.header("Filter Data")
all_countries = df['Country'].unique().tolist()
st.session_state.selected_countries = st.sidebar.multiselect(
"Select Countries",
options=all_countries,
default=st.session_state.selected_countries,
key="country_filter"
)
all_genders = df['Gender'].unique().tolist()
st.session_state.selected_genders = st.sidebar.multiselect(
"Select Genders",
options=all_genders,
default=st.session_state.selected_genders,
key="gender_filter"
)
# Filter by selected countries and genders
filtered_df = df[
(df['Country'].isin(st.session_state.selected_countries)) &
(df['Gender'].isin(st.session_state.selected_genders))
]
return filtered_df
# --- Step 4: Fragment Rendering for Targeted Updates ---
@st.fragment(run_every=5)
def display_realtime_metrics(df: pd.DataFrame):
"""
Displays real-time metrics, updated every 5 seconds using st.fragment.
"""
st.subheader("Real-time Metrics (Updates every 5s)")
if df.empty:
st.warning("No data available for metrics.")
return
col1, col2, col3 = st.columns(3)
with col1:
st.metric(label="Total Users", value=f"{len(df):,}")
with col2:
st.metric(label="Unique Countries", value=f"{df['Country'].nunique():,}")
with col3:
# Avoid division by zero if no unique countries
avg_users_per_country = len(df) / df['Country'].nunique() if df['Country'].nunique() > 0 else 0
st.metric(label="Avg Users per Country", value=f"{avg_users_per_country:.1f}")
# Plot for gender distribution
gender_counts = df['Gender'].value_counts()
if not gender_counts.empty:
fig, ax = plt.subplots(figsize=(4, 2))
gender_counts.plot(kind='bar', ax=ax, color=['skyblue', 'lightcoral'])
ax.set_title('Gender Distribution', fontsize=8)
ax.set_ylabel('Count', fontsize=6)
ax.tick_params(axis='both', which='major', labelsize=6)
plt.tight_layout()
st.pyplot(fig)
plt.close(fig) # Close the figure to free up memory
else:
st.info("No gender data to display chart.")
def main():
st.set_page_config(layout="wide", page_title="Dynamic User Demographics Dashboard")
st.title("Dynamic User Demographics Dashboard")
# Load and normalize data (cached)
full_df = fetch_and_normalize_data(num_results=100)
if full_df.empty:
st.error("Could not load demographic data. Please check the API status or your network connection.")
return
initialize_session_state(full_df)
# Apply filters from sidebar
filtered_df = apply_filters(full_df)
st.write(f"Displaying {len(filtered_df):,} users out of {len(full_df):,} total.")
# Display real-time metrics fragment
display_realtime_metrics(filtered_df)
st.subheader("Filtered User Data")
st.dataframe(filtered_df, use_container_width=True)
# Save a plot to file for verification/demonstration
if not filtered_df.empty:
country_counts = filtered_df['Country'].value_counts().head(10)
fig_country, ax_country = plt.subplots(figsize=(8, 5))
country_counts.plot(kind='barh', ax=ax_country, color='lightgreen')
ax_country.set_title('Top 10 Countries by User Count')
ax_country.set_xlabel('Number of Users')
ax_country.set_ylabel('Country')
plt.tight_layout()
plt.savefig('country_distribution.png')
plt.close(fig_country)
# st.success("Country distribution plot saved as country_distribution.png")
if __name__ == "__main__":
try:
main()
except Exception as e:
st.error(f"An unexpected error occurred in the main application loop: {e}")
st.exception(e) # Display full traceback in Streamlit
Expected Output
When you run this script (streamlit run your_script_name.py), you will see an interactive web dashboard in your browser. The dashboard will feature:
- A main title: "Dynamic User Demographics Dashboard".
- A sidebar on the left with multiselect filters for "Countries" and "Genders". Your selections will persist across reruns.
- A section displaying the total number of users currently shown based on filters.
- A "Real-time Metrics" section with three metric cards (Total Users, Unique Countries, Avg Users per Country) and a bar chart showing Gender Distribution. This section will automatically update every 5 seconds without refreshing the entire page.
- A "Filtered User Data" section showing a paginated DataFrame of the users matching your selected filters.
- A file named `country_distribution.png` will be saved in the same directory as your script, containing a bar chart of the top 10 countries by user count.
If there are API issues, you will see error messages and retries in the Streamlit app. If data fetching consistently fails, the dashboard will gracefully display an empty state and an error message.
Limitations and Tradeoffs
While this architecture significantly improves Streamlit dashboard performance and resilience, it's not a silver bullet. Streamlit is fundamentally unsuited for multi-tenant high-concurrency enterprise applications exceeding thousands of simultaneous active WebSocket sessions without horizontal container scaling behind an Nginx load balancer. The single-threaded Python execution model means complex, long-running computations for one user can block others. Furthermore, while @st.fragment helps with targeted updates, it doesn't solve the underlying stateless nature of Streamlit's reruns for the main script. For truly complex, multi-user, real-time applications requiring fine-grained control over frontend state, you might eventually need to consider traditional web frameworks like Flask/Django with a JavaScript frontend (React/Vue) and WebSockets, or specialized real-time platforms. The caching TTL is a judgment call; too short, and you hit the API too much; too long, and your "real-time" data becomes stale. It's a balance you must tune for your specific data volatility and API constraints.
Frequently Asked Questions
How do I handle concurrent state mutations when multiple users access the dashboard simultaneously?
Streamlit's st.session_state is user-session specific. Each user accessing the dashboard gets their own isolated session state. There are no direct concurrent state mutation issues *between* users within Streamlit itself. However, if multiple users trigger expensive background processes (e.g., model training), those could contend for shared resources on the server. For shared resources or truly global state, you'd need external mechanisms like a database, Redis, or a message queue, and manage access to them carefully.
What is the performance penalty of using @st.fragment with aggressive auto-refresh intervals?
While @st.fragment prevents a full page rerun, it still triggers a partial rerun for that fragment. If you set run_every to a very low value (e.g., 1 second) and the fragment contains computationally expensive operations or many UI elements, it can still consume significant CPU resources and network bandwidth for frequent updates. It's best used for small, lightweight, and quickly computable components. Excessive use with aggressive intervals can lead to a less responsive UI overall.
How can I securely store API rate-limit tokens or credentials within a Streamlit deployment?
Never hardcode credentials. For sensitive API keys, use Streamlit Secrets, which load environment variables from a .streamlit/secrets.toml file. On other deployment platforms, use environment variables (e.g., Docker, Kubernetes) or a dedicated secret management service (e.g., AWS Secrets Manager, HashiCorp Vault). Access them in your code via os.environ.get("MY_API_KEY") or st.secrets["api_key"].
Why does my Pandas dataframe lose its selection state when the cache invalidates?
If you're referring to selections made *within* a st.dataframe (like row selections), those are often transient and tied to the current render cycle of the dataframe. When @st.cache_data invalidates and refetches the underlying DataFrame, Streamlit re-renders the st.dataframe component from scratch, which resets any internal selections. To persist selections, you'd need to capture them explicitly using st.dataframe(..., on_select="rerun", selection_mode="multi-row") and store the selection indices in st.session_state, then reapply them if the dataframe structure allows.
What I'd Change
If I were to evolve this dashboard for a genuine enterprise setting, my immediate next step would be to introduce a proper logging and monitoring framework. Streamlit's default logging is minimal, and in production, understanding API call failures, cache hit rates, and user interaction patterns is critical for debugging and performance optimization. I'd integrate a structured logger like loguru or Python's native logging module, sending events to a centralized system like Elasticsearch or Datadog. Beyond that, for truly high-volume, continuously updating data streams, I would explore replacing the simple `requests` calls with an asynchronous client (like `httpx` or `aiohttp`) and orchestrating data updates with `asyncio` tasks. This would allow background data ingestion without blocking the main Streamlit thread, potentially feeding into a more sophisticated in-memory data store or even a local Redis instance that the Streamlit app could query, further decoupling the UI from external API latency. Finally, for complex filtering logic, I might consider a dedicated query engine like DuckDB to handle DataFrame operations more efficiently than raw Pandas, especially as the dataset scales beyond millions of rows.