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

Axios

import { withSapiom } from "@sapiom/axios";
import axios from "axios";

const client = withSapiom(axios.create(), {
  apiKey: process.env.SAPIOM_API_KEY,
});

// Search with AI-generated answer
const { data } = await client.post(
  "https://linkup.services.sapiom.ai/v1/search",
  {
    query: "What are the latest developments in quantum computing?",
    depth: "standard",
    outputType: "sourcedAnswer",
  }
);

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

Fetch

import { createFetch } from "@sapiom/fetch";

const fetch = createFetch({
  apiKey: process.env.SAPIOM_API_KEY,
});

// Search with AI-generated answer
const response = await fetch(
  "https://linkup.services.sapiom.ai/v1/search",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      query: "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.01 - $0.08/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

Search Results

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

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

Sourced Answer

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

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

Structured

const { data } = await client.post(
  "https://linkup.services.sapiom.ai/v1/search",
  {
    query: "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 Parameters

Parameter	Type	Required	Description
query	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
structuredOutputSchema	object	Required for structured	JSON schema for output
includeSources	boolean	No	Include sources with structured output

Linkup Pricing

Output Type	Price
searchResults	$0.01
sourcedAnswer	$0.08
structured	$0.08

Fetch Operation	Price
Standard fetch	$0.01
With JS rendering	$0.02

---

You.com

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

Endpoints

Method	Path	Description
POST	/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

Search

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

With Live Crawling

const { data } = await client.get(
  "https://you-com.services.sapiom.ai/v1/search",
  {
    params: {
      query: "TypeScript best practices 2024",
      count: 5,
      livecrawl: "web",
      livecrawlFormat: "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",
    ],
    format: "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
livecrawlFormat	string	No	html or markdown

Contents:

Parameter	Type	Required	Description
urls	string[]	Yes	URLs to fetch (1-10)
format	string	No	html or markdown (default: markdown)

You.com Pricing

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

Contents	Price
Per URL	$0.01

---

Error Codes

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