{"record":{"id":"f00deeb7d3392558","repo":"assafelovic/gpt-researcher","slug":"groundroute-api-key-not-found-set-the-groundroute","errorCode":null,"errorMessage":"GroundRoute API key not found. Set the GROUNDROUTE_API_KEY environment variable. Create a key at https://groundroute.ai/overview","messagePattern":"GroundRoute API key not found\\. Set the GROUNDROUTE_API_KEY environment variable\\. Create a key at https://groundroute\\.ai/overview","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"gpt_researcher/retrievers/groundroute/groundroute.py","lineNumber":31,"sourceCode":"class GroundRouteSearch:\n    \"\"\"GroundRoute multi-engine search retriever.\"\"\"\n\n    def __init__(self, query, headers=None, topic=\"general\", query_domains=None):\n        self.query = query\n        self.headers = headers or {}\n        self.topic = topic\n        self.base_url = \"https://api.groundroute.ai/v1/search\"\n        self.api_key = self.get_api_key()\n        self.query_domains = query_domains or None\n\n    def get_api_key(self):\n        \"\"\"Get the GroundRoute API key from headers or the environment.\"\"\"\n        api_key = self.headers.get(\"groundroute_api_key\")\n        if not api_key:\n            try:\n                api_key = os.environ[\"GROUNDROUTE_API_KEY\"]\n            except KeyError:\n                raise Exception(\n                    \"GroundRoute API key not found. Set the GROUNDROUTE_API_KEY \"\n                    \"environment variable. Create a key at https://groundroute.ai/overview\"\n                )\n        return api_key\n\n    def search(self, max_results=7):\n        \"\"\"Search via GroundRoute. Returns [{\"href\": url, \"body\": content}, ...].\"\"\"\n        try:\n            response = requests.post(\n                self.base_url,\n                headers={\n                    \"Authorization\": f\"Bearer {self.api_key}\",\n                    \"Content-Type\": \"application/json\",\n                },\n                json={\"query\": self.query, \"max_results\": max_results},\n                timeout=20,\n            )\n            response.raise_for_status()","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/assafelovic/gpt-researcher/blob/6f998577d547b1e54ec662dac63583aa11e3b84b/gpt_researcher/retrievers/groundroute/groundroute.py#L13-L49","documentation":"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.","triggerScenarios":"Constructing the GroundRoute retriever without a groundroute_api_key header and without GROUNDROUTE_API_KEY in the environment.","commonSituations":"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).","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."],"exampleFix":"# before\nretriever = GroundRoute(query=\"...\")\n\n# after\nretriever = GroundRoute(query=\"...\", headers={\"groundroute_api_key\": KEY})\n# or: export GROUNDROUTE_API_KEY=...","handlingStrategy":"validation","validationCode":"import os\nhas_key = os.environ.get(\"GROUNDROUTE_API_KEY\") or headers.get(\"groundroute_api_key\")\nif not has_key:\n    raise SystemExit(\"Provide groundroute_api_key header or GROUNDROUTE_API_KEY\")","typeGuard":"null","tryCatchPattern":"try:\n    retriever = GroundRoute(query, headers=headers)\nexcept Exception as e:\n    if \"GROUNDROUTE_API_KEY\" in str(e):\n        sys.exit(str(e))\n    raise","preventionTips":["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."],"tags":["groundroute","missing-env-var","api-key","retriever"],"backgroundTag":"missing-env-var","analyzedSha":"6f998577d547b1e54ec662dac63583aa11e3b84b","analyzedAt":"2026-08-28T17:50:07.383Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}