Guides

Getting the best results

Blopus is a search index, not a chat model. A few habits make the difference between thin results and good ones — most of them come down to how you write the query.

One query, one topic#

This is the single most common mistake, and it is usually made by an LLM driving the API. Search matches documents. If you merge unrelated subjects into one query, you are asking for a document that is about all of them at once — and no such document exists, so the results are poor or empty.

The API detects this and tells you: when a query looks like several topics glued together, the response carries a note field naming the topics and showing the split. If you are building an agent, surface note to the model — it is written to be read by one.

A conjunction is fine when it is genuinely one subject: "relationship between inflation and unemployment" and "Nvidia and AMD market share" are single topics and work normally.

Write like a search box#

Keep queries short and keyword-like — roughly 2 to 8 words. Full sentences, polite framing and instructions dilute the signal, because every extra word is another term the ranker has to satisfy.

Instead of	Use
"Could you find me some recent articles about what happened with the Fed interest rate decision?"	`Fed interest rate decision`
"I need information on how to configure kubernetes ingress"	`kubernetes ingress configuration`

Use `news_only` for events#

It restricts results to sources that employ journalists, which removes the vendor blogs, marketing pages and documentation that otherwise crowd out real reporting.

Set it	Do not set it
What happened, who announced what, latest developments, market reaction, election results, earnings news	Documentation, tutorials, forums, reference material — newsrooms do not write those
`"ECB rate decision"`	`"how does asyncio work"`, `"what is a dividend"`

If a question wants both — "what is new in Python 3.14" needs the announcement and the changelog — leave it off. An unscoped search returns everything, so omitting it is never wrong.

freshness filters, recency ranks#

freshness is a hard filter — pd, pw, pm, p3m, p1y. Use it when older material would be wrong, such as a breaking story.

recency only changes ranking. For timeless questions where the best answer may be months or years old, set recency: "off" so quality wins over date.

Triage on snippets, then fetch#

Every result carries a snippet. Read those first and fetch only the few pages you genuinely need in full — that is the cheapest path and usually the fastest.

Two things that save a lot of calls:

If you already know you need most of the page bodies, set include_content: true on the search and get the text inline in one call instead of N fetches. content_chars caps the length.
Fetching several URLs? Pass urls as a batch. A batch is one lookup billed at 1 credit per 10 URLs — a batch of 10 costs the same as a single search. Never loop single fetches.

Spend fewer credits#

Results are billed in blocks of 10, so count rounds up to 10/20/30/40/50. Leave it at 10 unless you know you need more — asking for 11 costs the same as 20.
Paginate with offset only when more_results is true.
Leave include_images off unless the user asked to see something — it costs tokens on every result.

If you are driving this from an LLM#

Decompose the user's request into topics before searching, then issue one call per topic in parallel.
Read the note field on every response and act on it — it explains clamped quota and merged-topic queries in plain language.
remaining_quota comes back on every response; use it to decide whether to fetch more or stop.
Over MCP the same rules are in the tool description — but the description is advice, and note is feedback about the call you just made. Prefer the latter.