Skip to main content

web.search Tool

Search the web and return structured results

Overview​

  • Type: Web search (DuckDuckGo backend — no API key required)
  • Capability: web.search
  • Egress: Required (controlled)
  • Modes: text · news · images

When to Use​

✅ Perfect for:

  • Information retrieval and research
  • Finding recent news on a topic
  • Discovering URLs to then read with web.fetch
  • Grounding an LLM answer with fresh links

❌ Not ideal for:

  • Reading full page content (use web.fetch)
  • Structured data extraction (use web.scrape)
  • High-volume crawling

Public Endpoint​

Ready to use — available as a public endpoint:

  • Endpoint: web-search-public
  • Pricing: per-request, billed in USD. See the Tools index or the live catalog (GET /api/builder/v1/actions?visibility=public) for the current price.
  • No setup required — just call the API

Quick Start​

from colabhive import ColabHive

client = ColabHive(
    api_key="your_api_key_here",
    account_id="your_account_id_here",
    base_url="https://api.colabhive.com",
)

result = client.endpoints.infer(
    endpoint_id="web-search-public",  # SDK auto-resolves the name
    input_data={
        "query": "vector databases 2024",
        "max_results": 5,
        "search_type": "text",
    },
)
print(result)

cURL (Alternative)​

curl -X POST "https://api.colabhive.com/api/builder/v1/endpoints/{ENDPOINT_ID}/infer" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "query": "vector databases 2024",
      "max_results": 5,
      "search_type": "text"
    }
  }'

Input Parameters​

ParameterTypeDefaultDescription
querystringrequiredSearch query (1–500 chars)
max_resultsint10Number of results (1–25)
search_typestring"text""text", "news", or "images"
regionstringworldwideRegion code, e.g. "us-en", "de-de", "wt-wt" (worldwide)
time_rangestringnone"d" (day), "w" (week), "m" (month), "y" (year)

Output Format​

{
  "query": "vector databases 2024",
  "search_type": "text",
  "results": [
    {
      "title": "Example result title",
      "url": "https://example.com/page",
      "snippet": "A short excerpt of the page...",
      "source": "example.com",
      "published": null,
      "image_url": null,
      "thumbnail_url": null
    }
  ],
  "total_results": 5,
  "duration_ms": 640,
  "region": "wt-wt"
}
  • published is populated for search_type: "news".
  • image_url / thumbnail_url are populated for search_type: "images".

Use Cases​

Research → Read pipeline​

# 1) Find candidate sources
search = client.endpoints.infer(
    endpoint_id="web-search-public",
    input_data={"query": "state space models explained", "max_results": 3},
)

# 2) Read the top result with web.fetch (extract the URL from the search result),
#    then feed the content to an LLM endpoint for a summary.

Recent News​

result = client.endpoints.infer(
    endpoint_id="web-search-public",
    input_data={
        "query": "semiconductor export policy",
        "search_type": "news",
        "time_range": "w",   # past week
        "max_results": 10,
    },
)

Limits & Security​

  • Results: 1–25 per call.
  • Timeout: enforced server-side (search calls are capped).
  • Network: isolated container with controlled egress.
  • Backend: DuckDuckGo via the ddgs library — no API key required, no per-provider quota to manage.

Next Steps​