Developer Tools

Cloudsway Search: Ranked Results + Summaries

Deep dive into Cloudsway Search on SandBase — ranked web search results with dynamic summaries for AI agents. Architecture, use cases, API usage, and comparison with semantic search approaches.

SandBase Team By SandBase Team
#search-api #cloudsway #web-search #developer-tools #agent-workflows #rag

TL;DR — Cloudsway Search is a web search API on SandBase that returns ranked results with dynamic summaries — designed for AI agents that need fresh, structured web data. One operation, clean output: titles, URLs, snippets, relevance scores, and optional full-text extraction. Best for research agents, fact-checking workflows, and competitive intelligence where you need authoritative, ranked results rather than semantic matching.

What Cloudsway Search does

Cloudsway Search is a search-as-a-service tool available through SandBase. Unlike LLM knowledge (frozen at training time) or vector databases (limited to your indexed content), Cloudsway gives your agent access to live web results — ranked by relevance, enriched with summaries.

The output is structured for agent consumption:

{
  "results": [
    {
      "title": "ByteDance Releases Seedream 5.0 Pro - AI Image Generation",
      "url": "https://example.com/seedream-5-release",
      "snippet": "ByteDance announced Seedream 5.0 Pro, their latest image generation model...",
      "score": 0.95,
      "published_date": "2026-07-15",
      "summary": "Seedream 5.0 Pro is ByteDance's production image model offering two variants..."
    },
    ...
  ],
  "query_interpretation": "image generation model bytedance 2026",
  "total_results": 142
}

Key features:

  • Ranked results — ordered by relevance, not just keyword matching
  • Dynamic summaries — AI-generated summaries of each result, tailored to the query context
  • Freshness — live web index, not stale cached data
  • Structured output — JSON ready for agent processing, no HTML parsing needed
  • Single operation — one API call gets you everything

API usage on SandBase

Cloudsway Search is accessed through SandBase’s /v1/run endpoint:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.sandbase.ai/v1",
    api_key="your-sandbase-api-key"
)

# Basic search
response = client.post("/v1/run", body={
    "model": "cloudsway/search",
    "operation": "search",
    "input": {
        "query": "best practices for AI agent memory architecture 2026",
        "num_results": 10
    }
})

results = response.json()["output"]["results"]
for r in results:
    print(f"[{r['score']:.2f}] {r['title']}")
    print(f"  {r['url']}")
    print(f"  {r['summary']}")
    print()

Advanced search parameters

# Search with filtering and options
response = client.post("/v1/run", body={
    "model": "cloudsway/search",
    "operation": "search",
    "input": {
        "query": "enterprise AI agent deployment strategies",
        "num_results": 20,
        "include_full_text": True,      # Include full page content
        "freshness": "month",           # Results from last month only
        "language": "en",               # Language filter
        "include_summary": True         # Generate per-result summaries
    }
})

results = response.json()["output"]["results"]

# Full text available for deeper analysis
for r in results[:3]:
    print(f"Title: {r['title']}")
    print(f"Full text length: {len(r.get('full_text', ''))} chars")
    print(f"Summary: {r['summary']}")

Understanding when to use Cloudsway vs. semantic search (like Exa) requires understanding what each does:

DimensionCloudsway (Ranked)Semantic search (e.g., Exa)
Matching methodRelevance ranking (BM25 + neural reranking)Embedding similarity
IndexLive web indexCurated web content
Best forFinding authoritative sources on a topicFinding content by meaning/concept
Query styleNatural language or keywordsNatural language descriptions
FreshnessReal-time webDepends on crawl frequency
OutputRanked list + summariesContent + similarity scores
StrengthsBreadth, freshness, authority signalsPrecision, conceptual matching

When to use Cloudsway:

  • “What are the latest developments in X?”
  • “Find authoritative sources about Y”
  • “What are people saying about Z?”
  • Competitive intelligence, market research, news monitoring

When to use semantic search:

  • “Find content similar to this document”
  • “What pages discuss the concept of X from angle Y?”
  • “Find resources that match this specific technical description”

Use cases for agents

Use case 1: Research agent

An agent that gathers information on a topic and produces a structured report:

class ResearchAgent:
    """Agent that uses Cloudsway Search to gather and synthesize information."""
    
    def __init__(self, api_key: str):
        self.client = OpenAI(
            base_url="https://api.sandbase.ai/v1",
            api_key=api_key
        )
    
    def research_topic(self, topic: str, depth: int = 3) -> dict:
        """Research a topic with multiple search passes."""
        
        # Pass 1: Broad overview
        overview_results = self._search(
            f"{topic} overview guide 2026",
            num_results=10
        )
        
        # Pass 2: Extract subtopics from results, search each
        subtopics = self._extract_subtopics(overview_results, topic)
        
        detailed_results = {}
        for subtopic in subtopics[:depth]:
            detailed_results[subtopic] = self._search(
                f"{topic} {subtopic} details",
                num_results=5
            )
        
        # Pass 3: Find contrarian/alternative viewpoints
        contrarian = self._search(
            f"{topic} challenges problems criticism",
            num_results=5
        )
        
        return {
            "overview": overview_results,
            "subtopics": detailed_results,
            "challenges": contrarian,
            "sources_count": self._count_unique_sources(
                overview_results, detailed_results, contrarian
            )
        }
    
    def _search(self, query: str, num_results: int = 10) -> list[dict]:
        response = self.client.post("/v1/run", body={
            "model": "cloudsway/search",
            "operation": "search",
            "input": {
                "query": query,
                "num_results": num_results,
                "include_summary": True
            }
        })
        return response.json()["output"]["results"]
    
    def _extract_subtopics(self, results: list[dict], topic: str) -> list[str]:
        """Use LLM to identify subtopics from search results."""
        summaries = "\n".join(r["summary"] for r in results if r.get("summary"))
        
        response = self.client.chat.completions.create(
            model="openai/gpt-4o-mini",
            messages=[{
                "role": "user",
                "content": f"Given these summaries about '{topic}', "
                          f"list 5 key subtopics to research deeper:\n\n{summaries}"
            }],
            max_tokens=200
        )
        
        return response.choices[0].message.content.strip().split("\n")
    
    def _count_unique_sources(self, *result_sets) -> int:
        urls = set()
        for results in result_sets:
            if isinstance(results, list):
                urls.update(r["url"] for r in results)
            elif isinstance(results, dict):
                for sub_results in results.values():
                    urls.update(r["url"] for r in sub_results)
        return len(urls)

Use case 2: Fact-checking agent

An agent that verifies claims by searching for supporting/contradicting evidence:

class FactCheckAgent:
    """Verify claims using web search evidence."""
    
    def __init__(self, api_key: str):
        self.client = OpenAI(
            base_url="https://api.sandbase.ai/v1",
            api_key=api_key
        )
    
    def verify_claim(self, claim: str) -> dict:
        """Check a claim against web sources."""
        
        # Search for supporting evidence
        support_results = self._search(f"{claim} evidence confirmed")
        
        # Search for contradicting evidence
        contra_results = self._search(f"{claim} debunked false incorrect")
        
        # Score confidence based on source quality and agreement
        confidence = self._score_confidence(support_results, contra_results)
        
        return {
            "claim": claim,
            "confidence": confidence,
            "verdict": self._verdict(confidence),
            "supporting_sources": support_results[:3],
            "contradicting_sources": contra_results[:3],
        }
    
    def _search(self, query: str) -> list[dict]:
        response = self.client.post("/v1/run", body={
            "model": "cloudsway/search",
            "operation": "search",
            "input": {"query": query, "num_results": 5, "include_summary": True}
        })
        return response.json()["output"]["results"]
    
    def _score_confidence(self, support: list, contra: list) -> float:
        support_score = sum(r.get("score", 0) for r in support)
        contra_score = sum(r.get("score", 0) for r in contra)
        total = support_score + contra_score
        if total == 0:
            return 0.5
        return support_score / total
    
    def _verdict(self, confidence: float) -> str:
        if confidence > 0.8:
            return "LIKELY TRUE"
        elif confidence > 0.6:
            return "POSSIBLY TRUE"
        elif confidence > 0.4:
            return "UNCERTAIN"
        elif confidence > 0.2:
            return "POSSIBLY FALSE"
        else:
            return "LIKELY FALSE"

Use case 3: Competitive intelligence

Monitor competitors’ latest moves:

class CompetitiveIntelAgent:
    """Track competitor activity using web search."""
    
    def __init__(self, api_key: str):
        self.client = OpenAI(
            base_url="https://api.sandbase.ai/v1",
            api_key=api_key
        )
    
    def monitor_competitor(self, competitor: str, aspects: list[str]) -> dict:
        """Gather latest intelligence on a competitor."""
        intel = {}
        
        for aspect in aspects:
            results = self._search(
                f"{competitor} {aspect} 2026",
                freshness="week"
            )
            intel[aspect] = {
                "findings": results[:5],
                "key_insight": self._summarize_findings(results, competitor, aspect)
            }
        
        return intel
    
    def _search(self, query: str, freshness: str = "month") -> list[dict]:
        response = self.client.post("/v1/run", body={
            "model": "cloudsway/search",
            "operation": "search",
            "input": {
                "query": query,
                "num_results": 10,
                "freshness": freshness,
                "include_summary": True
            }
        })
        return response.json()["output"]["results"]
    
    def _summarize_findings(
        self, results: list[dict], competitor: str, aspect: str
    ) -> str:
        summaries = "\n".join(
            f"- {r['summary']}" for r in results[:5] if r.get("summary")
        )
        
        response = self.client.chat.completions.create(
            model="openai/gpt-4o-mini",
            messages=[{
                "role": "user",
                "content": f"Summarize what we know about {competitor}'s "
                          f"{aspect} based on:\n{summaries}\n\n"
                          f"One paragraph, focus on actionable intelligence."
            }],
            max_tokens=150
        )
        return response.choices[0].message.content.strip()

# Usage
agent = CompetitiveIntelAgent(api_key="your-key")
intel = agent.monitor_competitor(
    competitor="OpenAI",
    aspects=["product launches", "pricing changes", "partnerships", "hiring"]
)

Cloudsway vs Exa: conceptual comparison

Both are available in the SandBase ecosystem but serve different purposes. For a detailed comparison, see our social media data APIs guide and best AI search APIs guide.

AspectCloudsway SearchExa Search
Search typeRanked web resultsSemantic content matching
Best query”AI agent frameworks comparison 2026""content that explains how agents decide which tool to use”
Result formatTitle + URL + snippet + summaryContent + highlights + similarity score
FreshnessReal-time webCrawl-dependent
BreadthEntire webCurated high-quality content
Agent patternResearch, monitoring, fact-checkingRAG, content discovery, recommendation
Analogy”Google for agents""Semantic finder for agents”

Integration patterns

Combining Cloudsway with RAG

Use Cloudsway to augment your RAG pipeline with fresh web data:

def augmented_rag_answer(query: str, vector_store_results: list, api_key: str):
    """Combine vector store results with live web search."""
    client = OpenAI(base_url="https://api.sandbase.ai/v1", api_key=api_key)
    
    # Get fresh web results
    web_response = client.post("/v1/run", body={
        "model": "cloudsway/search",
        "operation": "search",
        "input": {"query": query, "num_results": 5, "include_summary": True}
    })
    web_results = web_response.json()["output"]["results"]
    
    # Combine contexts
    internal_context = "\n".join(
        f"[Internal] {doc['content']}" for doc in vector_store_results
    )
    web_context = "\n".join(
        f"[Web: {r['url']}] {r['summary']}" for r in web_results
    )
    
    # Generate answer with combined context
    response = client.chat.completions.create(
        model="openai/gpt-4o",
        messages=[
            {"role": "system", "content": "Answer using both internal knowledge and web sources. Cite sources."},
            {"role": "user", "content": f"Question: {query}\n\nInternal sources:\n{internal_context}\n\nWeb sources:\n{web_context}"}
        ]
    )
    
    return response.choices[0].message.content

Pricing and usage

Cloudsway Search uses per-call pricing through SandBase:

Usage levelEstimated monthly costQueries/day
Light (development)$5–1510–50
Medium (production agent)$30–100100–500
Heavy (multi-agent research)$200–5001000–5000

Cost-per-query is significantly lower than running your own search infrastructure. No crawling, no indexing, no infrastructure management.

Conclusion

Cloudsway Search fills a specific gap in the agent toolchain: real-time, ranked web search with structured output. It’s not a replacement for semantic search or vector databases — it’s complementary. Use it when your agent needs to know what’s happening now, find authoritative sources, or validate claims against the live web.

The single-operation design keeps integration simple: one API call, structured JSON response, ready for agent consumption. Combined with SandBase’s unified billing and API management, it fits naturally into any multi-tool agent architecture.

You May Also Like

Cover image for Cloudsway vs Exa: Which Search API for Your Agent
Developer Tools

Cloudsway vs Exa: Which Search API for Your Agent

Detailed comparison of Cloudsway Search and Exa Search for AI agent workflows — ranked results vs semantic matching, when to use each, and how to combine them for maximum coverage.

Cover image for Batch Image Generation Pipeline for Agents
Developer Tools

Batch Image Generation Pipeline for Agents

Step-by-step tutorial for building a batch image generation pipeline — agent takes product descriptions, generates variants, scores them, picks the best. Python code with parallel generation, error handling, and cost tracking.

Cover image for Best Embedding Models for RAG Agents (2026)
Best Of

Best Embedding Models for RAG Agents (2026)

Ranked evaluation of the best embedding models for RAG agents in 2026 — text-embedding-v4, OpenAI text-embedding-3-large, Cohere embed-v3, Voyage-3. Dimensions, chunking strategies, cost per million tokens, and which model for which use case.