Search across 9 engines with a single endpoint. Supports Bing, Google, DuckDuckGo, Brave, YouTube, Amazon, eBay, Yandex, and Baidu.
The search endpoint proxies your query to the selected search engine and returns structured results. It supports all 9 engines through a single unified interface.
Results are automatically cached for 1 hour. Cached results cost only 1 credit instead of the full live search cost, making repeated queries much cheaper.
The q parameter is sanitised against SQL injection and XSS attacks. Maximum query length is 500 characters.
| Name | Type | Description |
|---|---|---|
qrequired | string | Search query. 1-500 characters. Sanitised against SQL injection and XSS. Required for all requests. |
engine | string | Search engine to use. Default: `bing`. Options: `bing`, `google`, `duckduckgo`, `brave`, `youtube`, `amazon`, `ebay`, `yandex`, `baidu`. |
pages | integer | Number of result pages to fetch. 1-10, default: `1`. Each page returns approximately 10 results. Multiple pages cost additional credits. |
safe | boolean | Enable safe search filtering to exclude explicit content. Default: `true`. |
num_results | integer | Maximum number of results to return. 1-50, default: `10`. Fewer results may return faster. |
location | string | Geographic location for localised results. Format: `City, Country` or `Country Code`. Example: `London, UK` or `US`. |
language | string | Language code for results. ISO 639-1 format. Example: `en`, `es`, `fr`, `de`, `ja`. |
type | string | Result type filter. Options: `web` (default), `images`, `videos`, `news`. Supported engines: Google, Bing, DuckDuckGo. |
Bing (default) — 3 credits, 30 RPM limit, burst: 5. Best all-around engine with good global coverage. Returns web, image, and video results.
Google — 10 credits, 10 RPM limit, burst: 2. Premium pricing due to higher infrastructure costs. Returns the most comprehensive results with strong localisation support. Supports type parameter for images, videos, and news.
DuckDuckGo — 3 credits, 60 RPM limit, burst: 10. Privacy-focused engine with the most permissive rate limits. Good for general web search.
Brave — 3 credits, 30 RPM limit, burst: 5. Independent search engine with good tech and privacy-focused content.
YouTube — 3 credits, 20 RPM limit, burst: 3. Searches YouTube videos, channels, and playlists. Returns video titles, descriptions, and durations.
Amazon — 3 credits, 10 RPM limit, burst: 2. Product search. Returns product titles, prices, ratings, and URLs.
eBay — 3 credits, 15 RPM limit, burst: 3. Auction and product search. Returns listings with prices and bid counts.
Yandex — 3 credits, 20 RPM limit, burst: 3. Best for Russian-language queries and Eastern European content.
Baidu — 3 credits, 10 RPM limit, burst: 2. Best for Chinese-language queries and Chinese web content.
Search credits depend on the engine and cache state:
Multiple pages cost additional credits. For example, fetching 3 pages from Bing costs 3 credits (1 per page). If the results are cached, all pages cost 1 credit total.
The response includes credits_charged and credits_remaining so you can track your spending.
Jiro caches search results in Redis with a 1-hour TTL (time-to-live). The cache key is a hash of the query, engine, pages, safe, num_results, location, language, and type parameters.
When you make a request that matches a cached query, the cached results are returned immediately with cached: true and only 1 credit is charged. This makes repeated searches against the same query very efficient.
Cache behaviour:
- Cache key includes all request parameters — changing any parameter creates a new cache entry
- TTL is 1 hour from the time the result was first cached
- Cached results include the original credits_charged value for transparency
- Self-hosted instances can configure or disable caching via ~/.jiro/config.yaml
- Cache is shared across all API keys on the same instance
Successful search response:
Search using each SDK:
This endpoint can return the following errors:
| Name | Type | Description |
|---|---|---|
INVALID_QUERY | 400 | Missing or invalid `q` field, unsupported engine name, or `pages` out of range (1-10). |
INSUFFICIENT_CREDITS | 402 | Not enough credits for this operation. Check your balance with GET /v1/status or `jiro status`. |
USER_RATE_LIMITED | 429 | You've exceeded your plan's per-minute rate limit. FREE: 60 RPM, PRO: 200 RPM, ENTERPRISE: 1,000 RPM. |
ENGINE_RATE_LIMITED | 429 | The target engine is rate-limited at the instance level. Try a different engine or wait a few seconds. |
ENGINE_ERROR | 502 | The search engine returned an unexpected error (timeout, 500, etc). Credits are automatically refunded. |
ENGINE_UNAVAILABLE | 503 | The engine's circuit breaker is open after 5 consecutive failures. Credits are automatically refunded. Try again in 60 seconds or use a different engine. |