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.
Basic Usage (Python)
Section titled “Basic Usage (Python)”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:
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" }'Accepted Parameters
Section titled “Accepted Parameters”| 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.
Example Response
Section titled “Example Response”{ "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. |
Errors
Section titled “Errors”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_filterfor news-style queries andsearch_domain_filterto restrict results to one site. - Use
content_size: "high"when the default 500-character excerpts are too short to work from.