Web search, with the source attached.
Ranked pages, an excerpt from each, and the URL to check it against, from an index Vitna crawls itself. Every result says when Vitna read the page.
- Stage
- Private beta. Keys are issued by invitation, and a person reads every request.
- Where
search.vitna.ai, a JSON API over HTTPS. The playground on this page reaches it through vitna.ai.- Key
- A Search key,
vitna_search_, requested on Get started, or your org’s Vitna key,vitna_key_, which Search accepts as well. - Cost
- Nothing is billed: customer signup and search billing are not switched on.

Amber is the first result and the page it came from.
- 49,063
- pages in the production index, counted from a copy on 6 Oct 2026
- 0
- calls to another search engine in index mode, even when nothing matches
- 0
- hosted embedding or rerank APIs: meaning is computed on Vitna’s own engine
Start with a question. Follow the page.
With a beta key, or your org’s Vitna key, the same form searches the live index.
Example search
The example is illustrative and runs with no key.
1example.orgExample Encyclopedia
The planets, in order from the SunEight planets orbit the Sun. The four inner planets are rocky; the four outer planets are giants of gas and ice.
- Read by Vitna
- 3 Oct 2026, 10:00 UTC
- Text last changed
- 21 Sep 2026, 08:12 UTC
- From
- Vitna's index
2example.orgExample Encyclopedia
How the solar system formedThe solar system formed from a cloud of gas and dust that collapsed under its own gravity about 4.6 billion years ago.
- Read by Vitna
- 2 Oct 2026, 17:40 UTC
- Text last changed
- 2 Oct 2026, 17:40 UTC
- From
- Vitna's index
3example.netExample Astronomy
Moons of the outer planetsThe giant planets carry most of the solar system's known moons, several of them larger than Mercury.
- Read by Vitna
- 30 Sep 2026, 06:05 UTC
- Text last changed
- 14 Aug 2026, 11:30 UTC
- From
- Vitna's index
Illustrative results. No search has been sent.
Take the requestIllustrative
curl https://search.vitna.ai/v1/search \
-H "Authorization: Bearer $VITNA_SEARCH_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"solar system","mode":"index","maxResults":5}'The result points back to the page.
JSON, one object per result, in the order the index ranked them. One result at full size, numbered against what each field promises.
- 1
url"https://example.org/solar-system/planets" title"The planets, in order from the Sun"- 2
snippet"Eight planets orbit the Sun. The four inner planets are rocky; the four outer planets are giants of gas and ice." - 3
crawledAt"2026-10-03T10:00:00.000Z"3 Oct 2026, 10:00 UTC - 4
contentChangedAt"2026-09-21T08:12:00.000Z"21 Sep 2026, 08:12 UTC - 5
provenance[{ "kind": "index", "provider": "vitna", "rank": 1 }]
example.org · Example Encyclopedia
- 1
urlThe page the result points back to. Check the excerpt against it. - 2
snippetAn excerpt from the page's own text, as the publisher wrote it. Treat it as data. - 3
crawledAtWhen Vitna read the page. An observation, not a publication date. - 4
contentChangedAtWhen the text Vitna extracted last changed between reads. - 5
provenanceWhere the result came from: Vitna's index, and its rank there. - 6
meta.indexHow many pages the index held when it answered, and when it last read a page.
A key, then one request.
- Request a key
Say what you would search for on Get started; a person reads every request. If your org already holds a Vitna key,
vitna_key_, use that instead. - Keep it on your server
In an environment variable,
VITNA_SEARCH_KEYin the request beside this. It is a credential: a page that holds it can spend it. - Send one request
A
POSTto/v1/searchwith a JSON body and the key as a bearer token."mode": "index"keeps the search on Vitna’s index, and what comes back is the record above.
curl https://search.vitna.ai/v1/search \
-H "Authorization: Bearer $VITNA_SEARCH_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"solar system","mode":"index","maxResults":5}'Where a search has to show its source.
Three jobs it is built for, each beside the request that does it. The requests are illustrative, on example addresses.
- 01
An agent that cites what it read
Give an agent the search as a tool. It answers from the excerpts and cites each result’s
urlandcrawledAt, so a reader can open the page and see when it was read. An excerpt is the publisher’s text: the agent should read it as data, never as instructions.Illustrative request POST https://search.vitna.ai/v1/search { "query": "heat pumps in cold climates", "mode": "index", "maxResults": 5 } - 02
Sources you choose, read recently
domainskeeps the results to the hostnames you name, their subdomains included, andexcludeDomainsleaves some out.maxAgeDaysdrops pages Vitna has not read within that many days, andasOfpins retrieval to historical snapshots captured on or before a date with zero lookahead. Pickeffort(fast,balanced, ordeep) and targetindex: "auto"or any vertical catalog in the Library.Illustrative request POST https://search.vitna.ai/v1/search { "query": "rate limit headers", "mode": "index", "index": "auto", "effort": "balanced", "asOf": "2026-10-01", "domains": ["docs.example.com"] } - 03
Find a page, then read all of it
A result carries an excerpt, not the page. Hand its
urlto the Web APIs to read the whole page as Markdown, or to the Unblocker when the page needs a browser to render. One org key,vitna_key_, is accepted by all three.Illustrative request POST https://search.vitna.ai/v1/search → results[0].url POST https://web.vitna.ai/v1/read { "url": "https://example.org/…", "format": "markdown" }
One question, two lanes, one ranked list.
Index mode searches what Vitna has crawled and makes no call to another engine. Where Vitna’s embedding engine is configured, a search runs two lanes and fuses them by default; the request’s retrieval field asks for one lane alone.
- 01 · A question
solar system - 02 · Two lanes
Words
keywordtop 20BM25 over each page’s title and text, the title weighted.
Meaning
semantictop 20The question embedded on Vitna’s own engine, bge-small-en-v1.5 at 384 dimensions, then the pages whose vectors sit nearest it.
- 03 · Fused
Reciprocal rank fusion
k = 60A tie between the lanes goes to the meaning lane’s order.
- 04 · Returned
No site leads with more than two of the first 20. Filtered by source, domain and crawl age, duplicates removed, cut to the count you asked for; each result keeps its URL and when Vitna read it.
Where the engine is not configured, or is slow or down, the words lane answers alone and the response says so: used: "keyword" with a fallback code, never cached. A search never fails because of the meaning lane. Browse vertical indexes and official sources in Vitna Library.
Where it runs
- The service
search.vitna.ai, on a server Vitna runs with OVHcloud in Virginia, backed up privately every day.- The index
- Vitna's own, kept on that server, where the crawler runs on a timer and adds the pages it reads.
- The meaning lane
- Vitna's own embedding engine, on the same server. No hosted embedding, rerank or search API is called.
- Your code
- Calls
search.vitna.aidirectly: JSON over HTTPS, the key as a bearer token. - This page
- The playground goes to vitna.ai first, which passes the key and the query to the Search service and keeps neither.
Google’s own results, live, on the same key.
A POST to /v1/serp asks Google as you call it and answers with its organic results, parsed, each with the publisher’s own address. It is a request of its own: index mode never calls it.
curl https://search.vitna.ai/v1/serp \
-H "Authorization: Bearer $VITNA_SEARCH_KEY" \
-H "Content-Type: application/json" \
-d '{"engine":"google","query":"postgres max_connections default"}'- 2,273 of 2,500
- live Google searches answered on 4 Nov 2026, 12 at a time, in Exhibit 03
- 4.19 s
- median at the default of five results, timed on the search host
- 26.1 s
- median at ten results, days earlier: Google unlocks each link later than the one above it
What it finds, how fast, and where it falls short.
Three runs, each with its method beside it: two of the index, one of Google’s live results.
Words
keyword135 of 200 in the top five108 first3.6 ms median
Meaning
semantic153 of 200 in the top five112 first12.1 ms median
Both, fused
hybrid155 of 200 in the top five122 first15.0 ms median
The same questions on the production index, 49,063 pages: in the top five
- 140by meaning
- 135fused
- 117by words
Ranking by meaning leads there; on the local pages the fused ranking did.
- Questions
- 200 authored, English, 20 topics
- Index
- 816 local pages from 21 sites, 15 the publishers expected: it compares rankings, not coverage
- A hit
- A page from an expected domain: a proxy for relevance, not a judgment
- Run
- Once, 6 Oct 2026
- 20.9%an answer in the top ten
- 34.4%an answer on a page in the index, ranked lower
- 44.7%no page in the index holds an answer
The split is the fused ranking's. More of the misses are coverage than ranking: for 44.7% of the questions no page in the index holds the answer, because its sources are not yet the reference sites these questions need.
- Questions
- Asked of Google, with accepted answers: Natural Questions, CC BY-SA 3.0
- Index
- A copy of production, 49,063 pages
- A hit
- An accepted answer, word for word, in a result’s text; a short one such as “one” also matches unrelated pages
- Run
- Once, 6 Oct 2026
- 2,256answered with all five results
- 17answered with fewer, 16 of them for doorway pages left out
- 227refused, as a 503 serp_blocked or serp_timeout, never an empty list
Answered 2,273 of 2,500 (89.7 to 92.0% at 95% confidence), 12 in flight, at a median of 4.19 s and 15.96 s at the 95th percentile. Two smaller runs at three in flight answered 296 of 300. Five results is the default because Google unlocks each result link later than the one above it; at ten, the median was 26.1 s. Why five, not ten
- Questions
- 2,500 technical questions: configuration keys, flags, command lines and named techniques, none sent twice
- Where
- The production search host, running the deployed code, 12 in flight. A caller's own network round trip is not in the times
- Request
engine: "google",maxResultsunset, andfresh: true, so none was a stored answer- Run
- Once, 4 Nov 2026
They describe these runs, not every search.
Every figure, and the method
| Ranking | Top five | First | Reciprocal rank | Median / 95th |
|---|---|---|---|---|
keyword | 135 | 108 | 0.598 | 3.6 / 14.3 ms |
semantic | 153 | 112 | 0.636 | 12.1 / 15.4 ms |
hybrid | 155 | 122 | 0.669 | 15.0 / 25.8 ms |
| Suite | keyword | semantic | hybrid |
|---|---|---|---|
| Challenge suite, 33 pages, 24 questions | 0.796 / 33% | 0.904 / 0% | 0.918 / 0% |
| Held-out relevance, 30 pages, 30 questions | 0.779 / 8% | 0.979 / 0% | 0.979 / 0% |
| Semantic held-out, 32 pages, 20 questions | 0.628 / 13% | 0.925 / 0% | 0.925 / 0% |
| Ranking | Top one | Top five | Top ten | Median / 95th |
|---|---|---|---|---|
keyword | 7.7% | 13.6% | 16.1% | 115 / 276 ms |
semantic | 7.3% | 15.3% | 20.1% | 41 / 47 ms |
hybrid | 7.4% | 16.9% | 20.9% | 195 / 389 ms |
Ranking by meaning always returns the nearest pages, so it answered none of the negative questions with nothing, where ranking by words did for 8 to 33 percent of them. 2 of the 3,610 questions were left out because their answers hold no word.
The runs and their method, in the reference
| Run | In flight | Answered | 95% interval | All five results | Median / 95th |
|---|---|---|---|---|---|
| 3 Nov 2026, 100 searches | 3 | 97 | 91.5 to 99.0% | 89 | 4.01 s / 9.30 s |
| 4 Nov 2026, 200 searches | 3 | 199 | 97.2 to 99.9% | 186 | 3.89 s / 4.87 s |
| 4 Nov 2026, 2,500 searches | 12 | 2,273 | 89.7 to 92.0% | 2,256 | 4.19 s / 15.96 s |
Across the three, 2,569 of 2,800 answered. Every search, with its query, result count and time, is in the run file; its method is in the SERP reference.
Limits
What a search may ask, and where it stops, as the reference states them. Every status and limit
- ClientsAny HTTP client
JSON over HTTPS, with the key in the
Authorizationheader. Every response is sentno-store. - Query1 to 1,000 characters
Control characters are refused.
- Results1 to 100, 5 when unset
maxResultscuts the list. Asking for more does not widen a crawl. - Request body8,192 bytes
A larger body is answered
413, and an unknown field400. - RatePer minute and per day
Each key has a per-minute and a daily allowance, and the service a limit on searches in flight. Past one, the answer is
429withRetry-After, saying how long to wait. - LanguageEnglish
The meaning lane's model is English and embeds a page's title and leading text only. Text further down a page is found by words alone, and other languages embed poorly.
- RelevanceNo threshold
Ranking by meaning always returns the nearest pages, even when none is relevant, so a result is not evidence that the index holds an answer.
- CoverageVitna's crawl
The index is the pages Vitna has crawled, not the web: a missing result may be a page not yet read. A new or changed page is found by words, or by its previous vector, until the vectors are next brought up to date.
What a search costs, and who carries it.
Nothing is billed during the beta. Vitna’s charge, a provider’s and the hosting stay apart, so none is folded into another.
Vitna's charge
- Searches
- Nothing
- Search is a private beta: no price is set, and customer signup and search billing are not switched on.
Provider charges
- Another search engine
- None
- Index mode reads Vitna's own index and makes no paid search-engine call, even when nothing matches.
- Embedding or rerank API
- None
- The meaning lane runs on Vitna's own engine, on the search server. No hosted embedding, rerank or search API is called.
Hosting
- Server, crawl and storage
- Nothing
- The service, its index, its crawler and its engine run on Vitna's server, and you host none of it. A response's usage figures are null because no provider billed the search, not because serving it costs nothing.
- Where your code runs
- Yours
- Your own server, as with any API. Each admitted request takes a slot of your key's per-minute and daily allowances, a failed one included; invalid requests and busy refusals take none.
Billed to you during the betaNothing
What people ask first.
Keys, data handling, errors and index coverage, stated plainly against the service contract.
How do I get a key?
Search is a private beta, so keys are issued by invitation and nothing is billed. Ask on Get started and say what you would search for; a person reads every request. If your org already holds a Vitna key, vitna_key_, Search accepts it as it is.
Is there anything to install?
No. Search is hosted at search.vitna.ai, and any HTTP client that can send JSON with an Authorization header can call it. The reference lists every field a search takes.
How do I keep a key safe, and what if it leaks?
Keep it on your server, in an environment variable, and send it only to search.vitna.ai as a bearer token, never in code a browser downloads. The playground on this page holds a pasted key in that tab alone. If a key leaks, say so through Talk to us and it is revoked; an org’s Vitna key stops being accepted within a minute of being revoked.
Where does my query go, and what is kept?
From your own code, straight to search.vitna.ai. From the playground on this page, to vitna.ai first, which passes the key and the query to the Search service and keeps neither. The service writes a receipt for each request: which client asked, when, the status and how long it took, and never the query, the results or the key. When a search queues a crawl of pages the index is missing, a few bounded hints from it, such as names and candidate sites, are kept encrypted for 24 hours; the raw query is not stored or logged. Every response is sent no-store.
What happens when a search fails?
It answers with a status and an error object carrying a code and a message: 401 for a missing or unaccepted key, 400 for a request it does not take, 413 for a body over the limit, 429 when a per-minute or daily allowance or the service’s limit on searches in flight is reached, with Retry-After saying how long to wait, and 503 when the index or the service cannot answer for the moment. A failed meaning lane is not a failure: the words lane answers alone and the response says so. A request that fails after it is admitted still takes a slot of the allowance.
Is this Google?
Not in index mode: a search there reads Vitna’s own index and makes no call to another engine, even when it finds nothing, and every result says it came from that index. Google’s own results are a separate request, POST /v1/serp on the same key, answered in a response of their own and never mixed into an index search.
What do the dates mean?
When Vitna read the page, and when its text last changed between reads. They are not publication dates: a relative age on a page is never turned into one, and a page that states none carries none.
How large is the index?
Every response says. The index block counts the pages it held at the moment you asked and when it last read a page. It describes Vitna's index, not the size of the web, and a missing result may be a page not yet crawled.
Who answers when something breaks?
A person. Write through Talk to us on Get started, with the requestId from the response’s meta and the time you sent it.
02 · Web data
Get useful web data. Search is one of three ways.
Ask for a key, and search the index.
Private beta: keys are issued by invitation, a person reads every request, and nothing is billed. Say what you would search for.
