> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhuntr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Research Agent

> Run focused GTM research with POST /research — account briefs, buyer research, and structured output.

`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](/guides/company-search), [Person search](/guides/person-search), and [Contact enrichment](/guides/contact-enrichment). `/research` returns `422 BULK_ENRICHMENT_REQUIRED` when a request needs per-entity enrichment beyond its budget.

## Basic request

```bash theme={null}
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:

1. **Your context** — what you sell and why you're researching
2. **One primary target** — company, person, or team
3. **The decision** the answer should support
4. **Specific facts** you need
5. **Date ranges** for time-sensitive work

<Tip>
  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."
</Tip>

## Structured output

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/concepts/research-vs-direct-endpoints)
* [POST /research](/api-reference) — full schema
* [Huntr MCP](/build-with-ai/huntr-mcp) — full API as MCP tools (`research` + search + enrichment)