Optimizes the user list API endpoints by preventing large base64 profile image data from being fetched from the database and serialized to JSON responses.
Problem
The /api/v1/users/ endpoint was taking 1.5-2 seconds to return just 30 users because each user's profile_image_url field contained embedded base64 image data (~35KB per user), resulting in ~1MB response payloads.
Solution
Added defer_profile_image parameter to Users.get_users() that uses SQLAlchemy's defer() to exclude the profile_image_url column from database queries
Override profile_image_url in responses with a URL path that points to the existing profile image endpoint
Changes
models/users.py: Add defer_profile_image parameter with defer(User.profile_image_url)
routers/users.py: Pass defer_profile_image=True and override with /api/v1/users/{id}/profile/image
Impact
Metric
Before
After
Response size (30 users)
~1 MB
~5 KB
Database I/O
Fetches ~35KB per user
Skips column
Non-breaking
The frontend already uses the /api/v1/users/{id}/profile/image endpoint for displaying avatars, so this change is transparent to clients.
Contributor License Agreement
By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.
Note
Deleting the CLA section will lead to immediate closure of your PR and it will not be merged in.
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.
## 📋 Pull Request Information
**Original PR:** https://github.com/open-webui/open-webui/pull/20638
**Author:** [@Classic298](https://github.com/Classic298)
**Created:** 1/13/2026
**Status:** ❌ Closed
**Base:** `dev` ← **Head:** `profile-image-perf`
---
### 📝 Commits (2)
- [`3b33f18`](https://github.com/open-webui/open-webui/commit/3b33f1847481bd8e884f94fb8aea12bf4bb94609) perf: defer profile_image_url in user list endpoints
- [`150d68c`](https://github.com/open-webui/open-webui/commit/150d68c288b718365af9245c4b94d6142582b5c6) simplified
### 📊 Changes
**1 file changed** (+11 additions, -4 deletions)
<details>
<summary>View changed files</summary>
📝 `backend/open_webui/models/users.py` (+11 -4)
</details>
### 📄 Description
## Summary
Optimizes the user list API endpoints by preventing large base64 profile image data from being fetched from the database and serialized to JSON responses.
## Problem
The /api/v1/users/ endpoint was taking 1.5-2 seconds to return just 30 users because each user's profile_image_url field contained embedded base64 image data (~35KB per user), resulting in ~1MB response payloads.
## Solution
- Added defer_profile_image parameter to Users.get_users() that uses SQLAlchemy's defer() to exclude the profile_image_url column from database queries
- Override profile_image_url in responses with a URL path that points to the existing profile image endpoint
## Changes
- models/users.py: Add defer_profile_image parameter with defer(User.profile_image_url)
- routers/users.py: Pass defer_profile_image=True and override with /api/v1/users/{id}/profile/image
## Impact
| Metric | Before | After |
|--------|--------|-------|
| Response size (30 users) | ~1 MB | ~5 KB |
| Database I/O | Fetches ~35KB per user | Skips column |
## Non-breaking
The frontend already uses the /api/v1/users/{id}/profile/image endpoint for displaying avatars, so this change is transparent to clients.
### Contributor License Agreement
By submitting this pull request, I confirm that I have read and fully agree to the [Contributor License Agreement (CLA)](https://github.com/open-webui/open-webui/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT), and I am providing my contributions under its terms.
> [!NOTE]
> Deleting the CLA section will lead to immediate closure of your PR and it will not be merged in.
---
<sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
📋 Pull Request Information
Original PR: https://github.com/open-webui/open-webui/pull/20638
Author: @Classic298
Created: 1/13/2026
Status: ❌ Closed
Base:
dev← Head:profile-image-perf📝 Commits (2)
3b33f18perf: defer profile_image_url in user list endpoints150d68csimplified📊 Changes
1 file changed (+11 additions, -4 deletions)
View changed files
📝
backend/open_webui/models/users.py(+11 -4)📄 Description
Summary
Optimizes the user list API endpoints by preventing large base64 profile image data from being fetched from the database and serialized to JSON responses.
Problem
The /api/v1/users/ endpoint was taking 1.5-2 seconds to return just 30 users because each user's profile_image_url field contained embedded base64 image data (~35KB per user), resulting in ~1MB response payloads.
Solution
Changes
Impact
Non-breaking
The frontend already uses the /api/v1/users/{id}/profile/image endpoint for displaying avatars, so this change is transparent to clients.
Contributor License Agreement
By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.