OpenSERP

Search one engine you choose and return its ranked web results. Use it when the engine matters (Yandex for Russian, Baidu for Chinese, Google for the widest index) or to page with start. If any engine will do, use any_search; to compare engines, use mega_search. Returns JSON: results (rank, title, url, snippet, domain, engine), pagination (has_more, next_start) and meta (request_id, took_ms, engines_failed). Cloud: 1 credit per 10 returned results. Errors return isError with status, error code and retry_after. On 429 or 503 wait retry_after; if an engine is blocked (CAPTCHA, 502/503), try another engine. Unsupported parameters return 400 and are not charged.

Query several engines in parallel and merge their web results into one list (mode balanced, the default). Each result keeps its source engine and rank, and clusters list each URL with its rank on every engine that found it. Use it to compare engines, check where a page ranks across engines, or widen coverage for research; it is slower and costs more than one engine. Balanced mode serves only the first page (start 0); mode any or fast behaves like any_search or fast_search. Returns JSON: results (rank, title, url, snippet, domain, engine), pagination (has_more, next_start) and meta (request_id, took_ms, engines_failed). Cloud: balanced is billed per engine that returns results. Errors return isError with status, error code and retry_after. On 429 or 503 wait retry_after; if an engine is blocked (CAPTCHA, 502/503), try another engine. Unsupported parameters return 400 and are not charged.

Return one web result set as fast as possible, from the engine with the best recent health and latency. Use it for quick lookups where the engine doesn't matter; use search to pick the engine, or any_search to set a fallback order. Returns JSON: results (rank, title, url, snippet, domain, engine), pagination (has_more, next_start) and meta (request_id, took_ms, engines_failed). Cloud: 1 credit. Errors return isError with status, error code and retry_after. On 429 or 503 wait retry_after; if an engine is blocked (CAPTCHA, 502/503), try another engine. Unsupported parameters return 400 and are not charged.

Try engines one at a time in the order you give and return the first result set that succeeds, e.g. engines [google, bing, duckduckgo]. Use it as a resilient default when you prefer one engine but need a fallback; use fast_search when the order doesn't matter. On Cloud a slow attempt can overlap with the next one. Returns JSON: results (rank, title, url, snippet, domain, engine), pagination (has_more, next_start) and meta (request_id, took_ms, engines_failed). Cloud: 1 credit. Errors return isError with status, error code and retry_after. On 429 or 503 wait retry_after; if an engine is blocked (CAPTCHA, 502/503), try another engine. Unsupported parameters return 400 and are not charged.

Search images on one engine you choose. Returns JSON results (rank, title, image url/thumbnail/width/height, source page_url and domain, engine) and pagination. Use mega_image to combine several engines. Cloud: cost scales with the number of returned images. Errors return isError with status, error code and retry_after. On 429 or 503 wait retry_after; if an engine is blocked (CAPTCHA, 502/503), try another engine. Unsupported parameters return 400 and are not charged.

Search images on several engines and merge them into one list (mode balanced, the default); each image keeps its source engine and rank, and duplicates are dropped. Use it when one engine gives too few or too similar images; use image_search for a single engine. Balanced mode serves only the first page; mode any or fast returns the first engine that succeeds. Output fields match image_search. Cloud: any/fast cost 1 credit, balanced depends on engines and image volume. Errors return isError with status, error code and retry_after. On 429 or 503 wait retry_after; if an engine is blocked (CAPTCHA, 502/503), try another engine. Unsupported parameters return 400 and are not charged.

Show the OpenSERP Cloud account behind OPENSERP_API_KEY: account (plan, credits_remaining) and lastResponse (request_id, credits used, engine) for the previous tool call in this session. Read-only and free. Use it to check the balance before a large batch or to see what a call cost. Self-hosted mode has no credits, so it returns an error there.

Takes no parameters.

List the engines this OpenSERP backend can use and whether they work right now. Self-hosted: each engine with initialized and circuit_state (open means it is failing, skip it). Cloud: per-engine web/image support and status (operational, loaded, down) with latency. Read-only and free. Call it when searches keep failing, then pick a healthy engine for search or the engines list.

Takes no parameters.

Fetch one URL and return its main content as Markdown, e.g. to read a page found by search. Returns JSON: url, title, description, markdown, text, headings, links (first 50), lang and meta.mode_used. Content over maxChars (default 20000) is cut and the result gets truncated: true. For two or more pages use batch_extract. Pages behind logins or bot walls can fail or come back thin; try mode rendered or another source. Cloud: 1 credit for a fast fetch, 3 when the page needs a browser, +1 with region; failed and empty pages are free. Errors return isError with status and error code.

Extract LLM-ready content from up to 20 URLs in one request. Prefer this over repeated extract calls when grounding an answer in several pages: it is one round-trip, and a URL that fails returns an item with an error instead of failing the batch. Returns results (url, page_content as Markdown, error when that URL failed; metadata with title, mode_used and, when cut, truncated and total_chars) and meta (requested, succeeded, failed). Cloud: billed per URL like extract; failed and empty URLs are free.