Skip to content

Web Search

CompactifAI’s web search endpoint searches the web and returns ranked results as structured data. No model is involved: the query is searched exactly as you write it, and you decide what to do with the results.

To have a model search and answer from the results instead, use the web_search tool of Chat Completions or the Responses API.

import requests
API_URL = "https://api.compactif.ai/v1/web_search"
API_KEY = "your_api_key_here"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
data = {
"search_query": "latest quantum computing news",
"count": 5,
"search_recency_filter": "oneWeek"
}
response = requests.post(API_URL, headers=headers, json=data)
for result in response.json()["search_result"]:
print(result["title"], result["link"])

The same request with curl:

Terminal window
curl https://api.compactif.ai/v1/web_search \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $COMPACTIFAI_API_KEY" \
-d '{
"search_query": "latest quantum computing news",
"count": 5,
"search_recency_filter": "oneWeek"
}'
Parameter Type Required Description
search_query string Yes The text to search for. Must not be blank; at most 70,000 characters.
count integer No Number of results to return, from 1 to 50. Default 10.
search_domain_filter string No Only return results from this domain, for example www.example.com.
search_recency_filter string No Only return results published within this window: oneDay, oneWeek, oneMonth, oneYear or noLimit (default).
content_size string No Maximum length of each result’s content: medium (500 characters, default) or high (2,500 characters). Many results are shorter.
request_id string No Your own unique id for the request, 6 to 64 characters. It is returned in the response; one is generated when you leave it out.
search_intent boolean No true adds a search_intent array to the response.
include_image boolean No true adds the page’s images to each result, in images.
search_engine string No Not used: there is a single search backend. Leave it out; a value the API does not recognise is rejected with 1214.
user_id, sensitive_word_check - No Accepted and ignored: they have no effect.

A field set to null counts as left out, and unknown fields are ignored.

{
"id": "web-search-6f1c0c1d2f4a4b7f9a0d0e7c1b2a3d4e",
"created": 1792500000,
"request_id": "8d0c5f3a7b1e4c2a9f6e1d3b5a7c9e0f",
"search_result": [
{
"title": "Quantum computing breakthrough announced",
"content": "Researchers reported a new error-correction result that ...",
"link": "https://news.example.com/quantum-breakthrough",
"media": "news.example.com",
"icon": "",
"refer": "ref_1",
"publish_date": "2026-10-10"
}
]
}
Field Description
id Identifier of this search, starting with web-search-.
created Unix timestamp, in seconds, of when the response was created.
request_id The request_id you sent, or the one generated for the request.
search_result Up to count results, best match first. An empty array when nothing was found.
search_intent Only with search_intent: true: an array with query, intent and keywords. The query is searched as written, so query and keywords repeat your query and intent is always SEARCH_ALL.

Each item of search_result has:

Field Description
title Title of the page.
content Excerpt of the page: at most 500 characters, or 2,500 with content_size: "high". Many are shorter.
link URL of the page.
media Host name of the site, without www..
icon URL of the site’s icon. An empty string when none is available.
refer Label of the result within this response: ref_1, ref_2, and so on.
publish_date Publication date of the page. An empty string when it is not known.
images Only with include_image: true: the URLs of the images on the page. An empty array when there are none.

The endpoint uses the standard error object (see Error handling), but error.code is a four-digit code:

code Status Meaning
1213 400 A required parameter is missing. error.param names it (search_query).
1214 400 A parameter is invalid, for example a count outside 1 to 50 or a blank search_query. error.param names it.
1210 400 The request body is invalid and the cause cannot be tied to one parameter.
1221 400 Web search is not enabled on this deployment.
1001 401 No Authorization header was sent.
1000 401 The API key was rejected.
1302 429 You have exceeded your rate limit. The Retry-After header says how long to wait.
1234 500 The search failed. Retry; if it persists, contact support with the error id in the message.
  • Use the same API key and headers as the other CompactifAI endpoints. Rate limits are shared too: see Rate limits.
  • Set search_recency_filter for news-style queries and search_domain_filter to restrict results to one site.
  • Use content_size: "high" when the default 500-character excerpts are too short to work from.