Search the Web

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

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

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

Provider	Best For	Pricing
Linkup	Structured extraction, sourced answers	$0.006 - $0.055/search
You.com	Live crawling, freshness filters	$0.006 - $0.01/search

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

Method	Path	Description
POST	`/v1/search`	Web search
POST	`/v1/search/price`	Get price estimate (free)
POST	`/v1/fetch`	Fetch URL as markdown
POST	`/v1/fetch/price`	Get fetch price estimate (free)

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

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}`);
}

const { data } = await client.post(
  "https://linkup.services.sapiom.ai/v1/search",
  {
    q: "What are the benefits of TypeScript?",
    depth: "standard",
    outputType: "sourcedAnswer",
  }
);

console.log(data.answer);
console.log("Sources:", data.sources);

const { data } = await client.post(
  "https://linkup.services.sapiom.ai/v1/search",
  {
    q: "Top 5 programming languages in 2024",
    depth: "deep",
    outputType: "structured",
    structuredOutputSchema: {
      type: "object",
      properties: {
        languages: {
          type: "array",
          items: {
            type: "object",
            properties: {
              name: { type: "string" },
              rank: { type: "number" },
              useCase: { type: "string" },
            },
          },
        },
      },
    },
    includeSources: true,
  }
);

console.log(data.languages);

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

Parameter	Type	Required	Description
`url`	string	Yes	URL to fetch
`renderJs`	boolean	No	Render JavaScript before extraction (default: `false`)
`includeRawHtml`	boolean	No	Include raw HTML in response (default: `false`)
`extractImages`	boolean	No	Extract image URLs from the page (default: `false`)

Linkup Search Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query
`depth`	string	Yes	`standard` or `deep`
`outputType`	string	No	`searchResults`, `sourcedAnswer`, or `structured`
`maxResults`	number	No	Maximum results (1-100)
`includeImages`	boolean	No	Include images in results
`includeDomains`	string[]	No	Only include these domains
`excludeDomains`	string[]	No	Exclude these domains
`fromDate`	date	No	Results from this date
`toDate`	date	No	Results until this date
`includeInlineCitations`	boolean	No	Include inline citations (only for `sourcedAnswer`)
`structuredOutputSchema`	object	Required for `structured`	JSON schema for output
`includeSources`	boolean	No	Include sources with structured output

Linkup Pricing

Depth	Price
standard	$0.006
deep	$0.055

Fetch Operation	Price
Standard fetch	$0.001
With JS rendering	$0.006

You.com

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

Endpoints

Method	Path	Description
GET	`/v1/search`	Web search
POST	`/v1/search/price`	Get price estimate (free)
POST	`/v1/contents`	Fetch URL contents
POST	`/v1/contents/price`	Get contents price estimate (free)

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

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}`);
}

const { data } = await client.get(
  "https://you-com.services.sapiom.ai/v1/search",
  {
    params: {
      query: "TypeScript best practices 2024",
      count: 5,
      livecrawl: "web",
      livecrawl_formats: "markdown",
    },
  }
);

for (const result of data.results.web) {
  console.log(`Title: ${result.title}`);
  console.log(`Content: ${result.content}`); // Full page markdown
}

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

Search:

Parameter	Type	Required	Description
`query`	string	Yes	Search query
`count`	number	No	Results count (1-100, default: 10)
`freshness`	string	No	`day`, `week`, `month`, or `year`
`country`	string	No	ISO 3166-2 country code
`language`	string	No	BCP 47 language code
`offset`	number	No	Result offset for pagination (0-9)
`safesearch`	string	No	`off`, `moderate`, or `strict`
`livecrawl`	string	No	`web`, `news`, or `all`
`livecrawl_formats`	string	No	`html` or `markdown`

Contents:

Parameter	Type	Required	Description
`urls`	string[]	Yes	URLs to fetch (1-10)
`formats`	string[]	No	`html`, `markdown`, or `metadata` (default: `["markdown"]`)
`crawl_timeout`	number	No	Timeout in seconds per URL, 1-60 (default: 10)

You.com Pricing

Result Count	Price
1-50 (Standard)	$0.006
51-100 (Extended)	$0.008

Contents	Price
Per request (1-10 URLs)	$0.01

Error Codes

Code	Description
400	Invalid request parameters
402	Payment required — ensure you’re using the Sapiom SDK
429	Rate limit exceeded