Skip to content
Sapiom Docs
Go To Dashboard

Search the Web

Give your agents real-time information from the web — raw search results, AI-generated answers with citations, or structured data extraction.

Ways to call this

Section titled “Ways to call this”

Reach web search from a step through the typed ctx.sapiom.search.webSearch client method — sapiom_dev_agents_check validates the call at author time. See Using Capabilities.

Quick Example

Section titled “Quick Example”
import { createFetch } from "@sapiom/fetch";


const sapiomFetch = createFetch({
  apiKey: process.env.SAPIOM_API_KEY,
  agentName: "my-agent",
});


// Search with AI-generated answer
const response = await sapiomFetch(
  "https://linkup.services.sapiom.ai/v1/search",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      q: "What are the latest developments in quantum computing?",
      depth: "standard",
      outputType: "sourcedAnswer",
    }),
  }
);


const data = await response.json();
console.log(data.answer);
console.log("Sources:", data.sources);

How It Works

Section titled “How It Works”

Sapiom provides access to two web search providers: Linkup and You.com. Both support AI-powered search with different strengths:

  • Linkup excels at structured data extraction and sourced answers
  • You.com excels at live crawling and freshness filters

Choose the provider that fits your use case. Both use the same SDK pattern — just point to the different endpoint.

Providers

Section titled “Providers”
ProviderBest ForPricing
LinkupStructured extraction, sourced answers$0.006 - $0.055/search
You.comLive crawling, freshness filters$0.006 - $0.01/search

Linkup

Section titled “Linkup”

Linkup provides three output modes:

  • Search Results — Raw search results with titles, URLs, and snippets
  • Sourced Answer — AI-generated answer with source citations
  • Structured — Extract data into a custom JSON schema

Endpoints

Section titled “Endpoints”
MethodPathDescription
POST/v1/searchWeb search
POST/v1/search/priceGet price estimate (free)
POST/v1/fetchFetch URL as markdown
POST/v1/fetch/priceGet fetch price estimate (free)

Base URL: https://linkup.services.sapiom.ai

Section titled “Search”
const { data } = await client.post(
  "https://linkup.services.sapiom.ai/v1/search",
  {
    q: "TypeScript best practices 2024",
    depth: "standard",
    outputType: "searchResults",
  }
);


for (const result of data.results) {
  console.log(`${result.title} - ${result.url}`);
}

Fetch URL

Section titled “Fetch URL”

Fetch and convert a web page to clean markdown:

const { data } = await client.post(
  "https://linkup.services.sapiom.ai/v1/fetch",
  {
    url: "https://example.com/article",
    renderJs: false,
  }
);


console.log(data.markdown);

Linkup Fetch Parameters

Section titled “Linkup Fetch Parameters”
ParameterTypeRequiredDescription
urlstringYesURL to fetch
renderJsbooleanNoRender JavaScript before extraction (default: false)
includeRawHtmlbooleanNoInclude raw HTML in response (default: false)
extractImagesbooleanNoExtract image URLs from the page (default: false)

Linkup Search Parameters

Section titled “Linkup Search Parameters”
ParameterTypeRequiredDescription
qstringYesSearch query
depthstringYesstandard or deep
outputTypestringNosearchResults, sourcedAnswer, or structured
maxResultsnumberNoMaximum results (1-100)
includeImagesbooleanNoInclude images in results
includeDomainsstring[]NoOnly include these domains
excludeDomainsstring[]NoExclude these domains
fromDatedateNoResults from this date
toDatedateNoResults until this date
includeInlineCitationsbooleanNoInclude inline citations (only for sourcedAnswer)
structuredOutputSchemaobjectRequired for structuredJSON schema for output
includeSourcesbooleanNoInclude sources with structured output

Linkup Pricing

Section titled “Linkup Pricing”
DepthPrice
standard$0.006
deep$0.055
Fetch OperationPrice
Standard fetch$0.001
With JS rendering$0.006

You.com

Section titled “You.com”

You.com provides fast web search with optional live crawling to fetch full page content from search results.

Endpoints

Section titled “Endpoints”
MethodPathDescription
GET/v1/searchWeb search
POST/v1/search/priceGet price estimate (free)
POST/v1/contentsFetch URL contents
POST/v1/contents/priceGet contents price estimate (free)

Base URL: https://you-com.services.sapiom.ai

Search

Section titled “Search”
const { data } = await client.get(
  "https://you-com.services.sapiom.ai/v1/search",
  {
    params: {
      query: "Best practices for building AI agents",
      count: 10,
    },
  }
);


for (const result of data.results.web) {
  console.log(`${result.title} - ${result.url}`);
}

Fetch Contents

Section titled “Fetch Contents”

Fetch content from specific URLs:

const { data } = await client.post(
  "https://you-com.services.sapiom.ai/v1/contents",
  {
    urls: [
      "https://example.com/article1",
      "https://example.com/article2",
    ],
    formats: ["markdown"],
  }
);


for (const content of data.contents) {
  console.log(content.markdown);
}

You.com Parameters

Section titled “You.com Parameters”

Search:

ParameterTypeRequiredDescription
querystringYesSearch query
countnumberNoResults count (1-100, default: 10)
freshnessstringNoday, week, month, or year
countrystringNoISO 3166-2 country code
languagestringNoBCP 47 language code
offsetnumberNoResult offset for pagination (0-9)
safesearchstringNooff, moderate, or strict
livecrawlstringNoweb, news, or all
livecrawl_formatsstringNohtml or markdown

Contents:

ParameterTypeRequiredDescription
urlsstring[]YesURLs to fetch (1-10)
formatsstring[]Nohtml, markdown, or metadata (default: ["markdown"])
crawl_timeoutnumberNoTimeout in seconds per URL, 1-60 (default: 10)

You.com Pricing

Section titled “You.com Pricing”
Result CountPrice
1-50 (Standard)$0.006
51-100 (Extended)$0.008
ContentsPrice
Per request (1-10 URLs)$0.01

Error Codes

Section titled “Error Codes”
CodeDescription
400Invalid request parameters
402Payment required — ensure you’re using the Sapiom SDK
429Rate limit exceeded