YouComWebSearch

Search the web using the You.com Search API and return results as Haystack Documents.

Key Features

• Works without configuration: when no API key is set, searches use You.com's keyless free tier (rate limited per IP).
• Switches to the keyed You.com Search API automatically when the YOUDOTCOM_API_KEY environment variable is set.
• Returns web and news results as structured documents with content, URL, and metadata.
• Supports filtering by freshness, country, language, and safe-search level.
• Configurable keyless_fallback to fail fast when a key is required rather than silently degrading.

Configuration

1. Drag the YouComWebSearch component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   1. Optionally create a secret with your You.com API key and set it as api_key. Use YOUDOTCOM_API_KEY as the environment variable name. For instructions, see Create Secrets. Without a key, the component uses the keyless free tier.
   2. Set top_k to control the maximum number of results (default: 10).
   3. Optionally set freshness, country, search_lang, and safesearch to refine results.
4. Go to the Advanced tab to configure keyless_fallback, extra_params, timeout, and max_retries.

Connections

YouComWebSearch receives a query string and returns a list of Document objects and a list of URLs. Connect its documents output to downstream components such as PromptBuilder for retrieval-augmented generation.

Source Code

To check this component's source code, open youcom_websearch.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  YouComWebSearch:
    type: haystack_integrations.components.websearch.youcom.youcom_websearch.YouComWebSearch
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - YOUDOTCOM_API_KEY
        strict: false
      top_k: 5
      freshness: week
      country: US

Using the Component in a Pipeline

# haystack-pipeline
components:
  websearch:
    type: haystack_integrations.components.websearch.youcom.youcom_websearch.YouComWebSearch
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - YOUDOTCOM_API_KEY
        strict: false
      top_k: 5

  prompt_builder:
    type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
    init_parameters:
      required_variables: "*"
      template:
      - role: user
        content: |
          Answer the question using the following search results:
          {% for doc in documents %}
          {{ doc.content }}
          {% endfor %}
          Question: {{ question }}

  llm:
    type: haystack.components.generators.chat.openai.OpenAIChatGenerator
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - OPENAI_API_KEY
        strict: false
      model: gpt-4o-mini

connections:
- sender: websearch.documents
  receiver: prompt_builder.documents
- sender: prompt_builder.prompt
  receiver: llm.messages

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - websearch.query
  - prompt_builder.question

outputs:
  replies: llm.replies

Parameters

Inputs

Parameter	Type	Description
query	str	The search query string.

Outputs

Parameter	Type	Description
documents	List[Document]	A list of documents containing search result content from web and news sections.
links	List[str]	A list of URLs from the search results.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
api_key	Secret	Secret.from_env_var("YOUDOTCOM_API_KEY", strict=False)	The You.com API key. Resolved leniently, so an unset key is not an error — see keyless_fallback.
keyless_fallback	bool	True	When True and no API key resolves, searches use the keyless free tier (rate limited per IP). When False, raises an error if no key is found.
top_k	Optional[int]	10	Maximum number of results per section (web, news). Maps to the count parameter (1–100).
freshness	Optional[str]	None	Only return results from within a time window: "day", "week", "month", "year", or a date range in "YYYY-MM-DDtoYYYY-MM-DD" format.
country	Optional[str]	None	Two-letter country code for the geographical focus of results (for example, "US", "DE").
search_lang	Optional[str]	None	Language of returned results in BCP 47 format (for example, "EN", "PT-BR").
safesearch	Optional[str]	None	Content moderation level: "off", "moderate", or "strict".
extra_params	Optional[Dict[str, Any]]	None	Additional query parameters passed directly to the You.com API (for example, {"include_domains": "nytimes.com,bbc.com"}).
timeout	int	10	Timeout in seconds for the HTTP request.
max_retries	int	3	Maximum number of retry attempts on transient failures.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
query	str		The search query string.
top_k	Optional[int]	None	Per-run override of the maximum number of results.

Related Information

• Pipeline Components
• Integrations Overview