assafelovic/gpt-researcher · error · Exception

GroundRoute API key not found. Set the GROUNDROUTE_API_KEY e

Error message

GroundRoute API key not found. Set the GROUNDROUTE_API_KEY environment variable. Create a key at https://groundroute.ai/overview

What it means

Exception raised by the GroundRoute retriever when no API key is available: it first checks request headers for groundroute_api_key, then falls back to the GROUNDROUTE_API_KEY environment variable; if both are absent it raises. The key authenticates all GroundRoute API calls.

Source

Thrown at gpt_researcher/retrievers/groundroute/groundroute.py:31

class GroundRouteSearch:
    """GroundRoute multi-engine search retriever."""

    def __init__(self, query, headers=None, topic="general", query_domains=None):
        self.query = query
        self.headers = headers or {}
        self.topic = topic
        self.base_url = "https://api.groundroute.ai/v1/search"
        self.api_key = self.get_api_key()
        self.query_domains = query_domains or None

    def get_api_key(self):
        """Get the GroundRoute API key from headers or the environment."""
        api_key = self.headers.get("groundroute_api_key")
        if not api_key:
            try:
                api_key = os.environ["GROUNDROUTE_API_KEY"]
            except KeyError:
                raise Exception(
                    "GroundRoute API key not found. Set the GROUNDROUTE_API_KEY "
                    "environment variable. Create a key at https://groundroute.ai/overview"
                )
        return api_key

    def search(self, max_results=7):
        """Search via GroundRoute. Returns [{"href": url, "body": content}, ...]."""
        try:
            response = requests.post(
                self.base_url,
                headers={
                    "Authorization": f"Bearer {self.api_key}",
                    "Content-Type": "application/json",
                },
                json={"query": self.query, "max_results": max_results},
                timeout=20,
            )
            response.raise_for_status()

View on GitHub (pinned to 6f998577d5)

Solutions

export GROUNDROUTE_API_KEY=<key> (create at https://groundroute.ai).
Or pass headers={'groundroute_api_key': <key>} when constructing the retriever.
Add the var to .env / deployment secrets and verify it loads.

Example fix

# before
retriever = GroundRoute(query="...")

# after
retriever = GroundRoute(query="...", headers={"groundroute_api_key": KEY})
# or: export GROUNDROUTE_API_KEY=...

Defensive patterns

Strategy: validation

Validate before calling

import os
has_key = os.environ.get("GROUNDROUTE_API_KEY") or headers.get("groundroute_api_key")
if not has_key:
    raise SystemExit("Provide groundroute_api_key header or GROUNDROUTE_API_KEY")

Type guard

null

Try / catch

try:
    retriever = GroundRoute(query, headers=headers)
except Exception as e:
    if "GROUNDROUTE_API_KEY" in str(e):
        sys.exit(str(e))
    raise

Prevention

Propagate request headers when constructing the retriever in request-scoped code.
Also set GROUNDROUTE_API_KEY as a safety net for background jobs.
Preflight the key at startup.

When it happens

Trigger: Constructing the GroundRoute retriever without a groundroute_api_key header and without GROUNDROUTE_API_KEY in the environment.

Common situations: Missing env var, or callers assuming header-based auth will be provided but constructing the retriever without headers (e.g. in background tasks that lost the request context).

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of assafelovic/gpt-researcher@6f998577d5 (2026-08-28). Data as JSON: /api/errors/f00deeb7d3392558. Report an issue: GitHub.