Search
POST /v1/search: the request, the fields it takes and the response.
Request
POST /v1/search takes a query and returns one ranked list. Unless you pin providers, Grounder routes it to the provider, or pair, most likely to answer it well.
curl https://api.grounder.net/v1/search \
-H "Authorization: Bearer $GROUNDER_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "what is the half-life of caffeine", "top_k": 5}'Request fields
| Field | Type | Meaning |
|---|---|---|
query | string | Required, up to 2,000 characters. |
top_k | integer | Results after merging, 1 to 100. Default 10. |
filters | object | domains, recency (rolling days or a date range), language; Ozone also takes publisher_ids, article_types, and temporal_sensitivity. A filter a provider can’t apply returns 400 unsupported_filter. |
include_text | boolean | Passage text with each result. Default true. |
requested_provider | string | Pin one provider for this query: ozone, tavily, exa, brave, perplexity, you, firecrawl, octen, parallel, or valyu. |
providers | string[] | Fan out to exactly these providers and merge. |
realtime | boolean | Latency-bound callers: route to a single fast provider. |
routing_settings | object | Your account’s routing settings for this search only, over the saved ones, never saved: weights (accuracy, speed, results, recency, cost), allowed_only, licensed_only, top_providers, providers, fallback, specialized and caps.search. See Routing. |
depth | string | How much the user wants back, from what they asked for: answer (a direct answer), extensive (a broad set of results or sources) or report (a multi-part research report). Leave it out when unsure. |
context.user_location | string | Where the user is (“Austin, Texas”), only when the user said so. Never a guess. |
context.user_time_zone | string | The user’s time zone as an IANA name (“America/Chicago”), only when the user said so. Never a guess. |
Response
A response to what is the half-life of caffeine, recorded on 7 October 2026, before Licensed sources only was on by default (its routing policy label is today’s): two of its five results shown, passage text shortened. found_by lists every provider that returned the URL; licensed is true for Ozone’s licensed publisher content.
{
"query": "what is the half-life of caffeine",
"results": [
{
"rank": 1,
"url": "https://www.ncbi.nlm.nih.gov/books/NBK223808/",
"domain": "ncbi.nlm.nih.gov",
"title": "Pharmacology of Caffeine - Caffeine for the Sustainment of Mental Task Performance - NCBI Bookshelf",
"text": "Pharmacology of Caffeine - Caffeine for the Sustainment of Mental Task Performance - NCBI…",
"score": 1,
"provenance": {
"provider": "exa",
"found_by": ["perplexity", "exa"],
"licensed": false,
"promoted": "none"
}
},
{
"rank": 2,
"url": "https://www.efsa.europa.eu/sites/default/files/corporate_publications/files/efsaexplainscaffeine150527.pdf",
"domain": "efsa.europa.eu",
"title": "Caffeine - EFSA",
"text": "In adults the half-life of caffeine – the time it takes for the body to eliminate\n50% of t…",
"published_date": "2026-08-22",
"score": 1,
"provenance": {
"provider": "perplexity",
"found_by": ["perplexity"],
"licensed": false,
"promoted": "none"
}
}
],
"routing": {
"policy": "ranked",
"calls": [
{ "provider": "perplexity", "status": "ok", "latency_ms": 194, "result_count": 3 },
{ "provider": "exa", "status": "ok", "latency_ms": 2158, "result_count": 3 }
]
},
"usage": {
"latency_ms": 2537,
"cached": false,
"licensed_result_count": 0
},
"request_id": "2f696c9c-c80a-4dd6-b03f-465455b35c3a"
}With Allowed sources only on (see Routing), the response also carries allowed, an array with one entry for each provider that answered, sorted by provider: { "provider": "exa", "allowed_pct": 100, "checked": 4 }. Of that provider’s distinct results that Grounder could check, allowed_pct is the share whose site’s robots.txt allows the provider and does not opt out of search or AI answers, to one decimal, or null when none could be checked, and checked is how many it checked. A result that could not be checked is left out of both, and a provider that does not crawl the open web, such as Ozone, is always 100. Every result returned then has provenance.allowed set to true. With the setting off, neither field is in the response. allowed reports; it is not part of any score.