Research Agent

POST /research is Huntr’s agent-led endpoint. You send one objective; Huntr gathers live web and enrichment data, then returns a synthesized answer. Use it when you need judgment and narrative — not just a single database field.

When to use it

Good fits

Account plan before a first meeting
Buyer or team brief on one company
Competitive or diligence question with a clear scope
Buying-signal investigation with date ranges

Poor fits — use list-building and enrichment endpoints instead

Build a list of 500 companies
Find emails for every row in a CSV
Repeatedly fetch the same tech-stack field at scale

For bulk workflows, use Company search, Person search, and Contact enrichment. /research returns 422 BULK_ENRICHMENT_REQUIRED when a request needs per-entity enrichment beyond its budget.

Basic request

curl --request POST \
  --url https://api.tryhuntr.com/research \
  --header 'content-type: application/json' \
  --header "x-api-key: ${HUNTR_API_KEY}" \
  --data '{
    "prompt": "We sell financial infrastructure to internet businesses. Research Patrick Collison and the team he leads at Stripe. Summarize his role, leadership priorities, public statements from June 2025 through June 2026, and practical conversation angles.",
    "tier": "deep"
  }'

Write prompts that work

Strong prompts include:

Your context — what you sell and why you’re researching
One primary target — company, person, or team
The decision the answer should support
Specific facts you need
Date ranges for time-sensitive work

Bad: “Tell me about Stripe.” Better: “We sell fraud-prevention APIs to fintech platforms. Research Stripe’s enterprise initiatives from June 2025–June 2026 and identify partnership angles and deal risks.”

Structured output

Pass a flat schema map when downstream code needs predictable keys:

{
  "prompt": "Account plan for Stripe as a fraud-prevention vendor...",
  "tier": "deep",
  "schema": {
    "summary": "Concise account summary",
    "recommended_angles": "Array of partnership angles",
    "risks": "Array of deal risks"
  }
}

Keys = top-level result fields
Values = descriptions of what each field should contain
Not JSON Schema — no nested type definitions

Responses include confidence per field: live, model, or not_found.

Choose a tier

Tier	Use when
`lite`	Web-only research — news, pages, public signals
`standard`	Company account research with enrichment
`deep`	People, emails, LinkedIn — buyer-level research

Call GET /pricing or use the MCP get_pricing tool for current prices.

Async execution

Add callback_url for webhook delivery:

{
  "prompt": "...",
  "tier": "deep",
  "callback_url": "https://your-server.com/huntr/webhook"
}

The API returns 202 with request_id and poll_url. Poll GET /research/{request_id}/status until completed or failed. Credits are reserved up front and refunded on failure.

Response fields

Field	Description
`result`	Answer string or schema object
`data_source`	`live`, `mixed`, or `model` (free-text responses)
`confidence`	Per-field source labels (structured responses)
`tier` / `model`	What ran
`price`	USD charged
`request_id`	For support and async polling

Next step

Research vs direct endpoints
POST /research — full schema
Huntr MCP — full API as MCP tools (research + search + enrichment)

Getting started

Concepts

Guides

Build with AI

Integrations

Reference

Research Agent

When to use it

Basic request

Write prompts that work

Structured output

Choose a tier

Async execution

Response fields

Next step

​When to use it

​Basic request

​Write prompts that work

​Structured output

​Choose a tier

​Async execution

​Response fields

​Next step

When to use it

Basic request

Write prompts that work

Structured output

Choose a tier

Async execution

Response fields

Next step