GroundRoute
Sign inGet API key

Quickstart

Get from zero to your first search in under five minutes.

1. Sign up

Create an account at groundroute.ai. A free account is BYOK-only (you bring your own engine keys) and is capped and rate-limited — enough to build and test against. To run managed searches (GroundRoute holds the engine keys), add a payment method or credits in the console. See Pricing.

2. Create an API key

In the console, open API keys and create a key. The plaintext key — it looks like gr_live_… — is shown once. Store it in a secret manager; GroundRoute only ever stores its hash and can never show it again.

export GROUNDROUTE_API_KEY="gr_live_xxxxxxxxxxxxxxxxxxxx"

3. Your first search

Send the key as a Bearer token to POST /v1/search:

curl -s https://api.groundroute.ai/v1/search \
  -H "Authorization: Bearer $GROUNDROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "pgvector vs qdrant benchmark", "mode": "auto", "max_results": 5}'

You get back a normalized response — results plus the meta blocks that make GroundRoute a control plane, not just a proxy:

{
  "request_id": "8f1c…",
  "tenant_id": "…",
  "results": [
    {
      "url": "https://example.com/...",
      "title": "pgvector vs Qdrant: a benchmark",
      "snippet": "…",
      "source_engine": "serper",
      "rank": 0
    }
  ],
  "answer": null,
  "citations": [],
  "degraded": false,
  "routing_meta": { "strategy": "price_led", "chosen_engine": "serper", "cost_usd": 0.001 },
  "cache_meta":   { "cache_tier": "miss", "cost_avoided_usd": 0.0 },
  "quality_meta": { "quality_score": null },
  "usage_meta":   { "cost_usd": 0.001, "provider_key_source": "platform", "billable": true }
}

Response headers also carry X-Request-Id, X-Cache-Tier, and X-Degraded. Full reference: Search API.

Same call in Python

import os, httpx

resp = httpx.post(
    "https://api.groundroute.ai/v1/search",
    headers={"Authorization": f"Bearer {os.environ['GROUNDROUTE_API_KEY']}"},
    json={"query": "pgvector vs qdrant benchmark", "mode": "auto", "max_results": 5},
    timeout=15,
)
resp.raise_for_status()
data = resp.json()
for r in data["results"]:
    print(r["rank"], r["title"], r["url"])
print("engine:", data["routing_meta"]["chosen_engine"], "| cache:", data["cache_meta"]["cache_tier"])

4. Add it to an agent over MCP

GroundRoute ships an MCP server, so an agent can call search as a native tool. Point any MCP client at https://api.groundroute.ai/mcp with the same Bearer key.

Claude Desktop / Cursor (mcp.json):

{
  "mcpServers": {
    "groundroute": {
      "type": "http",
      "url": "https://api.groundroute.ai/mcp",
      "headers": { "Authorization": "Bearer gr_live_YOUR_KEY" }
    }
  }
}

Restart the client and the search tool is available. Full reference: MCP server.

Next

PreviousIntroductionNextAuthentication