Skip to content
Agentic Levels
Start hereLevelsTracksPromptsAbout
Get my levelGet my level

  • Start hereYour first useful task with AI.
  • Level quiz8 questions. No AI needed.
  • Fluency ScoreYour Level and a score, from your own AI.

  • LevelsThe 11 levels, in order.
  • LessonsShort lessons, filter by level.
  • TracksGuided paths by tool, role or goal.
  • Set up your AI tool
  • Starter packFree files that help AI remember.

  • PromptsReady prompts to copy and adapt.
  • ChatGPT vs Claude vs GeminiPick the right one for the job.
  • How-tos
  • ReferenceCommands for Claude Code, Codex, Antigravity.
  • ResourcesHand-picked reading and tools.

  • Your progress
  • Your next moveAn interview that picks your next skill.
  • Your next lessonsThe next lessons at your level.
  • Updates

  • Pricing
  • About
  • FAQ & Feedback
  • Work with us
  • How we handle your data
Sign inPreferences
AboutPricingHow-tosPromptsStarter packMy stackHow we handle your data

© 2026 Fuentes Studio

PrivacyTermsRefundsAccessibilityAI content policyCredits
yourCouncil
Ready to help
✦

What do you want to understand?

Ask anything about what you're learning.

←How-to guides
  1. Resources
  2. ›How-to guides

How to use GPT-Researcher

Autonomous research agent that breaks questions into parallel sub-queries, searches each independently, and synthesizes a cited report.

Levels 4 to 6On GitHub

Single-pass LLM research misses angles, lacks citations, and can't handle questions that need breadth across many sources. GPT-Researcher spawns parallel search agents per sub-query, compresses results with GPTR-Context to fit your context window, and returns a structured report with citations, all without manual orchestration. It supports local document modes, multiple LLM providers, and both Python and REST API access patterns.

Before you start

Python 3.11+ and pip. API keys for your chosen LLM provider (OpenAI, Anthropic, etc.) and a web search provider (Tavily recommended). Run pip install gpt-researcher to install.

  1. 1Install and configure environment
  2. 2Run your first research report
  3. 3Use local docs mode for private or offline research
  4. 4Switch to the REST API for pipeline integration
  5. 5Save the report as a reference artifact

Steps

01

Install and configure environment

Install via pip and set your API keys as environment variables. GPT-Researcher uses a .env file by default. Copy the sample from the repo and fill in your keys. Tavily provides the best search quality for research tasks; the free tier covers initial testing.

Install and set up
pip install gpt-researcher # Create .env with your keys: OPENAI_API_KEY=[YOUR_OPENAI_KEY] TAVILY_API_KEY=[YOUR_TAVILY_KEY] # Or for Anthropic: ANTHROPIC_API_KEY=[YOUR_ANTHROPIC_KEY]
[YOUR_OPENAI_KEY]OpenAI API key (or use Anthropic) e.g. sk-proj-...
[YOUR_TAVILY_KEY]Tavily search API key e.g. tvly-...
02

Run your first research report

Pass a research question and a report type. RESEARCH_REPORT is the standard full report with citations. DETAILED_REPORT produces a longer, more comprehensive output. SUBTOPIC_REPORT covers a narrow aspect in depth. Start with RESEARCH_REPORT and a question you know well so you can evaluate accuracy.

Run via Python
from gpt_researcher import GPTResearcher import asyncio async def main(): researcher = GPTResearcher( query="[YOUR_RESEARCH_QUESTION]", report_type="research_report" ) await researcher.conduct_research() report = await researcher.write_report() print(report) asyncio.run(main())
[YOUR_RESEARCH_QUESTION]Your research question e.g. What are the production trade-offs between LangGraph and CrewAI for multi-agent orchestration?
03

Use local docs mode for private or offline research

Set DOC_PATH in your .env to point to a folder of local documents. GPT-Researcher will search only those files instead of the web, useful for internal docs, research papers, or any corpus you cannot send to a search API.

Configure local docs mode
# In .env: DOC_PATH=./my-docs RETRIEVER=local # Then run the same Python code with your question
04

Switch to the REST API for pipeline integration

GPT-Researcher ships a FastAPI server for integration into pipelines. Start the server with `python -m gptr`, then POST your query to the endpoint. The API returns the same report types as the Python library, making it easy to call from any language.

Start the API server
python -m gptr # Then in another terminal: curl -X POST http://localhost:8000/report \ -H "Content-Type: application/json" \ -d '{"query": "[YOUR_QUESTION]", "report_type": "research_report"}'
[YOUR_QUESTION]Your research question e.g. How does HNSW indexing compare to flat search for high-dimensional vectors?
05

Save the report as a reference artifact

Write the report to a markdown file and reference it in subsequent Claude sessions. A report with citations is a first-class context artifact. Pass it to Claude Code alongside your task to ground its answers in real sources.

Save report to file
# Add to your async main(): with open("research-[TOPIC_SLUG].md", "w") as f: f.write(report) print("Saved to research-[TOPIC_SLUG].md")
[TOPIC_SLUG]Short label for the file e.g. multi-agent-orchestration

How do you know it worked?

  • The report cites specific sources, not just general claims.
  • The output covers multiple distinct angles on your question, not one line of reasoning.
  • DETAILED_REPORT and RESEARCH_REPORT produce noticeably different output lengths for the same query.
  • Local docs mode returns results only from your specified folder.
  • The REST API responds to a POST request and returns a valid report.

If something looks off

Search API costs on long queries
GPT-Researcher fires multiple search queries per research run. Tavily charges per search. Broad questions with many sub-queries can consume credits quickly. Scope your question tightly or set a max_subtopics limit for expensive runs.
Report quality depends on search provider
The default DuckDuckGo retriever is free but produces weaker results than Tavily. For any research you plan to act on, use Tavily or another paid provider. The quality difference is significant.
Citations are not verified
GPT-Researcher includes the sources it found, but does not verify that quotes are accurate or that sources exist at those URLs. Spot-check claims before treating the report as authoritative.

Skills & Commands Reference

Key GPT-Researcher commands, report types, and configuration options.

Command / SkillWhat it doesWhen to use it
python -m gptrStart the FastAPI REST server for pipeline and multi-language integrationIntegrating GPT-Researcher into a larger pipeline or calling from a non-Python service
--queryThe research question, passed as the first argument or query paramEvery research run, be specific about domain, constraints, and what you want to compare
--report_typeControls report format: research_report, detailed_report, or subtopic_reportChoose based on depth needed: research_report for broad summaries, detailed_report for deep dives
RESEARCH_REPORTStandard output: multi-section report with cited sources, covering the question from multiple anglesDefault choice for most research tasks, balanced depth and breadth
DETAILED_REPORTadvancedExtended report with deeper sub-topic coverage and more citationsComplex questions where you need exhaustive coverage before making a decision
SUBTOPIC_REPORTadvancedNarrow focused report on a specific aspect of a broader topicFollow-up research on a specific claim or aspect from a prior RESEARCH_REPORT
DOC_PATH (local docs mode)advancedSet in .env to point at a folder, GPT-Researcher searches only those documentsPrivate corpora, internal docs, research papers, or any content you cannot send to a web search API

What you'll do, 5 steps

  1. 1Install and configure environment
  2. 2Run your first research report
  3. 3Use local docs mode for private or offline research
  4. 4Switch to the REST API for pipeline integration
  5. 5Save the report as a reference artifact

Was this helpful?