`search_mode` parameter causes 400 error despite being documented in Best Practices

[GOROman]

search_mode parameter causes 400 error despite being documented in Best Practices

Description

The search_mode parameter is documented in the Search Best Practices guide with example code, but when used with the Python SDK, it returns a 400 error stating that this filter is not yet supported.

Environment

• Python SDK version: perplexityai==0.12.0
• Python version: 3.13.5
• OS: macOS (Darwin 24.4.0)

Documentation Reference

The Search Best Practices guide shows the following example:

# For general information and current events
web_search = client.search.create(
    query="latest tech news",
    search_mode="web",
    search_recency_filter="day"
)

# For research and academic information
academic_search = client.search.create(
    query="machine learning algorithms",
    search_mode="academic",
    search_domain_filter=["arxiv.org", "scholar.google.com"]
)

Additionally, the SDK source code (perplexity/resources/search.py:55) defines search_mode with type hints:

search_mode: Optional[Literal["web", "academic", "sec"]] | Omit = omit,

Steps to Reproduce

1. Install the SDK: pip install perplexityai==0.12.0
2. Run the following code:

import os
from perplexity import Perplexity

client = Perplexity(api_key=os.getenv("PERPLEXITY_API_KEY"))

search = client.search.create(
    query="latest AI developments 2024",
    max_results=5,
    search_mode="web"  # This parameter causes the error
)

for result in search.results:
    print(f"{result.title}: {result.url}")

Expected Behavior

The search should execute successfully with the search_mode="web" parameter, returning web search results as documented.

Actual Behavior

The API returns a 400 error:

Error code: 400 - {'error': {'message': 'The following filters are not yet supported: search_mode', 'type': 'forbidden_filters', 'code': 400}}

Error type: BadRequestError

Full Error Output

Testing search with search_mode parameter...
------------------------------------------------------------
Error occurred: Error code: 400 - {'error': {'message': 'The following filters are not yet supported: search_mode', 'type': 'forbidden_filters', 'code': 400}}

Error type: BadRequestError

Workaround

Remove the search_mode parameter from the request:

search = client.search.create(
    query="latest AI developments 2024",
    max_results=5
    # search_mode="web"  # Removed to avoid error
)

Verified Working Code

Testing search WITHOUT search_mode parameter...
------------------------------------------------------------
Success! Results:
1. Year in review: Google's biggest AI advancements of 2024
   https://blog.google/technology/ai/2024-ai-extraordinary-progress-advancement/

2. The State of AI: Global survey
   https://www.mckinsey.com/capabilities/quantumblack/our-insights/the-state-of-ai

3. The Top Artificial Intelligence Trends - IBM
   https://www.ibm.com/think/insights/artificial-intelligence-trends

4. AI Pulse: Top AI Trends from 2024 - A Look Back | Trend Micro (US)
   https://www.trendmicro.com/en_us/research/25/a/top-ai-trends-from-2024-review.html

5. The 2025 AI Index Report | Stanford HAI
   https://hai.stanford.edu/ai-index/2025-ai-index-report

API Reference

According to the Search API Reference, the documented parameters are:

• query (required)
• max_results (optional)
• max_tokens_per_page (optional)
• country (optional)

Notably, search_mode is not listed in the API reference, which conflicts with the Best Practices documentation.

Questions

1. Is search_mode supported by the current API server?
2. If not yet implemented, when is it expected to be available?
3. Should the Best Practices documentation be updated to reflect the current API capabilities?

Additional Context

The discrepancy between the SDK type definitions, Best Practices documentation, and actual API server capabilities creates confusion for developers. It would be helpful to either:

• Enable search_mode support on the API server side, or
• Update the documentation and SDK to remove references to unsupported parameters until they are available

[james-pplx]

Hey @GOROman - the search_mode parameter is not yet supported by the API. We have removed it from the documentation and will let you know when it is available.

[GOROman]

@james-pplx Understood, and appreciate the quick docs fix. I’ll hold off on search_mode.