Quickstart

Get an API key, run a research request, and understand what comes back.

1. Get an API key

Fastest path: open the Huntr dashboard, sign up, and copy your API key. API signup (for programmatic onboarding):

curl --request POST \
  --url https://api.tryhuntr.com/keys/create \
  --header 'content-type: application/json' \
  --data '{ "email": "you@company.com" }'

Click the verification link in your email. Your key is returned once — store it securely.

export HUNTR_API_KEY="hntr_live_xxxxxxxxxxxx"

Never put your API key in browser code, public repos, or client-side apps. Server-side and agent tooling only.

2. Check your balance

curl https://api.tryhuntr.com/balance \
  -H "x-api-key: ${HUNTR_API_KEY}"

See Billing and pricing for plan-aware pricing and usage guidance.

3. Run your first research request

POST /research takes one focused objective and returns a synthesized answer. Start with tier: "standard" for company-level research.

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 cloud cost-optimization software to large enterprises. Research Shell'\''s IT and digital organization: who owns cloud infrastructure and FinOps decisions, initiatives announced from December 2024 through June 2026, and practical conversation angles tied to cost pressure.",
    "tier": "standard"
  }'

Example response:

{
  "success": true,
  "request_id": "req_example",
  "result": "Shell's current cloud-efficiency priorities include...",
  "data_source": "live",
  "tier": "standard",
  "model": "gemini-2.5-flash",
  "price": 0.027,
  "credits_remaining": 4.973
}

Field	Meaning
`result`	The researched answer (string when no schema is provided)
`data_source`	`live` = grounded in retrieved data; `mixed` = retrieved + stable model knowledge; `model` = no usable retrieval
`price`	Amount charged for this request, based on the API key’s active pricing plan
`request_id`	Use for logs and support

4. Request structured output

When your workflow needs predictable top-level fields, pass a flat schema map. Keys become result fields; values describe what each field should contain.

curl --request POST \
  --url https://api.tryhuntr.com/research \
  --header 'content-type: application/json' \
  --header "x-api-key: ${HUNTR_API_KEY}" \
  --data '{
    "prompt": "We provide fraud-prevention APIs for fintech platforms and are building an account plan for Stripe. Research enterprise product initiatives from June 2025 through June 2026, partnership angles for a fraud-prevention company, and deal risks.",
    "tier": "deep",
    "schema": {
      "summary": "Concise account summary",
      "recommended_angles": "Array of concrete partnership angles",
      "risks": "Array of risks that could stall the deal"
    }
  }'

The schema value is a field map, not JSON Schema. Nested schema definitions are not supported. Structured responses include a confidence object per field (live, model, or not_found). Fields marked not_found are returned as null.

5. Try a direct endpoint

When you know exactly what you need, direct endpoints are faster and cheaper than /research. Search companies and read total from the response:

curl --request POST \
  --url https://api.tryhuntr.com/company-search \
  --header 'content-type: application/json' \
  --header "x-api-key: ${HUNTR_API_KEY}" \
  --data '{
    "query": {
      "industry": { "include": ["Software Development"] },
      "country_code": { "include": ["US"] }
    },
    "pagination": { "size": 10 }
  }'

Find a work email for one person:

curl --request POST \
  --url https://api.tryhuntr.com/person-email \
  --header 'content-type: application/json' \
  --header "x-api-key: ${HUNTR_API_KEY}" \
  --data '{
    "first_name": "Patrick",
    "last_name": "Collison",
    "company_url": "stripe.com"
  }'

Choose your workflow

Decide between /research and direct endpoints before you build.

Company search

Build ICP lists with structured filters and pagination.

Research agent

Write prompts that produce account-ready briefs.

Huntr MCP

Connect Huntr to Cursor, Claude, or Codex.

Getting started

Concepts

Guides

Build with AI

Integrations

Reference

1. Get an API key

2. Check your balance

3. Run your first research request

4. Request structured output

5. Try a direct endpoint

What to read next

Choose your workflow

Company search

Research agent

Huntr MCP

​1. Get an API key

​2. Check your balance

​3. Run your first research request

​4. Request structured output

​5. Try a direct endpoint

​What to read next

Choose your workflow

Company search

Research agent

Huntr MCP

1. Get an API key

2. Check your balance

3. Run your first research request

4. Request structured output

5. Try a direct endpoint

What to read next