Why your SearXNG JSON search tool fails on public instances

When integrating SearXNG’s JSON search API into your tool, you might assume it works consistently across all public instances. However, developers often encounter silent failures where the tool returns no results—or worse, throws JSON parsing errors—without any clear indication why. This inconsistency stems from a fundamental misconfiguration in how public SearXNG instances handle JSON output.

The hidden limitation in SearXNG’s JSON API

SearXNG, a privacy-focused metasearch engine, disables JSON output by default in its configuration file. In the settings.yml file, the search.formats list determines which output formats an instance supports. If json is omitted or commented out, the instance will reject JSON requests entirely, returning a 403 Forbidden error. This behavior is intentional, as operators often disable lightweight output formats like JSON to prevent automated scraping that consumes bandwidth.

The issue isn’t just a missing feature—it’s a deliberate design choice documented in SearXNG’s administration and API guides. Without explicit activation, JSON remains inaccessible, forcing developers to either reconfigure the instance or adapt their tools to work around the limitation.

Silent failures that break your workflow

Even when a public instance appears to respond with a 200 OK status, the underlying body might not contain JSON at all. During testing on July 2, 2026, several real public instances demonstrated this inconsistency:

• searx.be: Returned a 403 Forbidden error, explicitly blocking JSON requests.
• baresearch.org and search.bus-hit.me: Both returned a 200 OK response, but the body contained an anti-bot challenge page instead of JSON.
• searx.stream: Issued a 307 Temporary Redirect, further complicating the request flow.

The most problematic cases involve responses labeled as successful (200 OK) but filled with HTML—such as anti-bot pages. Standard error handling, like response.raise_for_status(), won’t catch these discrepancies. Instead, your code may process the HTML as JSON, only to fail when parsing throws a ValueError or JSONDecodeError. If your tool silently falls back to an empty result set, the failure remains invisible, masking the real issue: the instance never delivered valid JSON.

Best practices to avoid unexpected failures

To prevent your SearXNG integration from collapsing under inconsistent public instances, follow these guidelines:

• Avoid hardcoding a single instance. Public instances vary widely in their configurations. Instead of relying on one URL, use a curated list like searx.space, which tracks which instances support specific output formats.
• Validate responses before parsing. Check the Content-Type header for application/json before calling .json(). This simple step converts silent failures into clear errors, such as "This instance does not serve JSON."
• Self-host if reliability matters. If your tool depends on consistent JSON output, consider running your own SearXNG instance. Volunteers who maintain public instances often disable JSON to manage bandwidth costs, making self-hosting a more sustainable solution.

The bigger picture: Transparency vs. assumptions

SearXNG’s documentation explicitly outlines these behaviors, yet developers frequently overlook them while debugging. The root cause isn’t a bug—it’s a mismatch between assumptions and reality. By testing against multiple instances early in development and validating responses rigorously, you can avoid the frustration of tools that work on paper but fail in practice.

For developers building tools that rely on SearXNG’s JSON API, the lesson is clear: read the docs, test thoroughly, and never assume uniformity across public instances. The right approach ensures your integration remains robust, transparent, and free from hidden pitfalls.