Staan
Getting Started

Web Search API

Search the web and retrieve a ranked list of results — title, URL, snippet, and display metadata — in a single API call.

Code
GET https://api.staan.ai/v2/search/web POST https://api.staan.ai/v2/search/web

Not sure which endpoint to use?

Use Web Search API when you need a standard SERP. For RAG pipelines or LLM context, use Web Search for AI API which adds scored content chunks and full page extraction.

GET and POST

Both methods are supported and behave identically: GET with query-string parameters, POST with a JSON body. Only the array-based domain filters include_domains / exclude_domains require POST — see Domain filtering.

Quick start

TerminalcURL — GET
curl "https://api.staan.ai/v2/search/web?q=open+source+llms&market=en-us" \ -H "Authorization: Bearer YOUR_API_KEY"
TerminalcURL — POST
curl -X POST "https://api.staan.ai/v2/search/web" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"q": "open source llms", "market": "en-us"}'
Python
import requests response = requests.get( "https://api.staan.ai/v2/search/web", params={"q": "open source llms", "market": "en-us"}, headers={"Authorization": "Bearer YOUR_API_KEY"}, ) results = response.json()["web"]["results"]
TypeScriptTypeScript
const res = await fetch('https://api.staan.ai/v2/search/web', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ q: 'open source llms', market: 'en-us' }), }); const { web } = await res.json();

Authentication

Every request must include an Authorization header:

Code
Authorization: Bearer YOUR_API_KEY

Parameters

Parameters are sent as a query string (GET) or a JSON body (POST). Both methods behave identically, except include_domains and exclude_domains which are POST-only.

ParameterTypeMethodsDefaultDescription
qstringGET · POST—Search query. Max 400 characters. Supports site: / -site: operators — see Domain filtering.
marketstringGET · POSTfr-frLanguage and region. See supported markets.
offsetnumberGET · POST0Pagination offset. Values: 0, 10, 20, 30 (10 results per page).
countnumberGET · POST10Number of results. Fixed at 10.
include_domainsstring[]POST—Restrict results to these domains or site sections, e.g. linkedin.com/in (max 20). Mutually exclusive with exclude_domains. See Domain filtering.
exclude_domainsstring[]POST—Exclude these domains or site sections from results (max 20). See Domain filtering.
TerminalGET example
curl "https://api.staan.ai/v2/search/web?q=climate+tech+startups&market=en-us" \ -H "Authorization: Bearer YOUR_API_KEY"
JSONPOST body example
{ "q": "climate tech startups", "market": "en-us", "include_domains": ["techcrunch.com", "theverge.com"] }

Domain filtering

Restrict a search to specific domains, or exclude them. Two equivalent approaches are available:

  1. Operators inside q — Google-style site: and -site:. Works with GET and POST:

    TerminalCode
    curl "https://api.staan.ai/v2/search/web?q=climate+tech+site:lemonde.fr+-site:reddit.com&market=fr-fr" \ -H "Authorization: Bearer YOUR_API_KEY"
    • site:example.com — keep only results from example.com.
    • -site:example.com — exclude results from example.com.
    • Multiple inclusions are supported, both space-separated and with OR chains: site:a.com OR site:b.com.
    • The operators are stripped from the query before it is sent to the search engine; the query.q returned in the response keeps your original input.
  2. Dedicated fields — include_domains / exclude_domains. POST only (arrays don't map cleanly to a query string):

    JSONCode
    { "q": "climate tech", "market": "fr-fr", "include_domains": ["lemonde.fr", "lesechos.fr"] }

Both approaches can be combined: operators found in q and the dedicated fields are merged and de-duplicated.

Filtering on a section of a site

Both approaches also accept a path after the domain, to restrict a search to one section of a site — for example LinkedIn profiles (linkedin.com/in) or posts (linkedin.com/posts):

JSONCode
{ "q": "data engineer paris", "include_domains": ["linkedin.com/in", "linkedin.com/posts"] }

The same works inline: data engineer paris site:linkedin.com/in. Entries must be lowercase, without www. nor protocol; paths may contain letters, digits, -, _ and /.

Which approach should I use?

The two approaches serve different intents — who decides the restriction:

The restriction comes from…Use
The query itself — end users typing advanced-search operators, or LLM agents that naturally emit Google syntaxsite: / -site: operators in q
Your application — an allowlist/blocklist defined in your config, enforced regardless of what the query saysinclude_domains / exclude_domains

In short: site: operators let query authors (human or AI) express source restrictions inline — they work as-is, no parsing needed on your side. The dedicated fields give your application programmatic control over the domain scope, with each entry validated as a domain, optionally followed by a path.

Constraints

  • Max 20 domains for inclusion and 20 for exclusion. More than 20 entries in include_domains or exclude_domains returns a 400; site: / -site: operators in q count toward the same limit, and those beyond it are dropped (the request is not rejected).
  • include_domains and exclude_domains are mutually exclusive — do not send both.
  • Domain filtering is available on all markets (fr-fr, en-us, de-de).

Supported markets

French (fr-fr) · English (en-us) · German (de-de)

Response

JSONExample response
{ "search_id": "01906c9e-7e3f-7000-8000-abc123def456", "query": { "q": "open source llms", "market": "en-us", "count": 10, "offset": 0 }, "web": { "results": [ { "title": "Top open-source LLMs in 2024", "url": "https://www.example.com/open-source-llms", "snippet": "A comprehensive guide to the best open-source large language models...", "display_url": "www.example.com > ai > open-source-llms", "hostname": "www.example.com", "favicon_url": "https://s.qwant.com/v1/fav/..." } ] } }

Response fields

FieldTypeAlways presentDescription
search_idstringYesUUID v7 — include in support tickets.
query.qstringYesQuery sent by the client.
query.altered_querystringNoPresent if the search engine rewrote the query.
query.marketstringYesMarket used.
query.countnumberYesNumber of results returned.
query.offsetnumberYesOffset used.
web.results[].titlestringYesPage title.
web.results[].urlstringYesPage URL.
web.results[].snippetstringYesPreview from the search provider (original SERP order, not reranked).
web.results[].display_urlstringYesHuman-readable path (e.g. example.com > blog > post).
web.results[].hostnamestringYesDomain name.
web.results[].favicon_urlstringNoWebsite favicon, when available.
web.results[].thumbnailstringNoPage thumbnail, when provided by the search provider.

Limits

LimitValue
Rate limit20 req/s — excess traffic is rejected
Max query length400 characters
Results per page10 (fixed)
Max offset30

Queries over 400 characters or above the rate limit will be rejected. Implement exponential backoff in production clients.

Query tips

This endpoint works best with concise, keyword-style queries. Long, detailed prompts (e.g. "Suggest a fresh seasonal recipe for July, for 8 people, ready in under 30 minutes") may yield weaker results.

Last modified on