curl --request POST \
  --url https://api.tryhuntr.com/research \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "prompt": "We sell cloud cost-optimization software to large enterprises. Research Shell's IT and digital organization, who owns cloud infrastructure and FinOps decisions, cloud or efficiency initiatives announced from December 2024 through June 2026, relevant technology partners, and practical conversation angles tied to current cost pressure.",
  "tier": "deep"
}
EOF

{
  "success": true,
  "request_id": "req_1746123456_ab3x9k",
  "result": "Shell's current cloud-efficiency priorities include...",
  "data_source": "live",
  "tier": "deep",
  "model": "gemini-2.5-flash",
  "price": 0.046,
  "credits_remaining": 4.954
}

Research

Run a research task

Requires x-api-key header.

Rate limit: 5 requests/second per API key.

Use /research for one focused research objective: an account brief, person or team brief, competitive question, diligence task, buying-signal investigation, or decision-oriented analysis. The agent selects relevant research and enrichment capabilities, gathers current web data, and synthesizes either a written answer or structured JSON.

Best results: name one primary target, explain your business context and the decision the research should support, request specific facts, and use explicit date ranges for time-sensitive work.

Choose another endpoint for bulk workflows: use /company-search to discover many companies, /person-search to find people across a list, and /person-email for repeatable contact enrichment. /research rejects multi-entity workflows whose per-item enrichment would exceed its request budget; rejected requests are not charged.

Sync execution is the default. Add callback_url for asynchronous execution, then poll the returned status URL until the request is completed or failed.

POST

research

curl --request POST \
  --url https://api.tryhuntr.com/research \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "prompt": "We sell cloud cost-optimization software to large enterprises. Research Shell's IT and digital organization, who owns cloud infrastructure and FinOps decisions, cloud or efficiency initiatives announced from December 2024 through June 2026, relevant technology partners, and practical conversation angles tied to current cost pressure.",
  "tier": "deep"
}
EOF

{
  "success": true,
  "request_id": "req_1746123456_ab3x9k",
  "result": "Shell's current cloud-efficiency priorities include...",
  "data_source": "live",
  "tier": "deep",
  "model": "gemini-2.5-flash",
  "price": 0.046,
  "credits_remaining": 4.954
}

Authorizations

x-api-key

string

header

required

Your Huntr API key. Get one at tryhuntr.com. Pass as x-api-key header on all authenticated requests.

Body

application/json

prompt

string

required

The research question or task. Be specific about the context and output your workflow needs.

tier

enum<string>

default:standard

Controls which capabilities are available and the synthesis model. lite ($0.018) = search + scraping. standard ($0.027) = + extraction + company enrichment. deep ($0.046) = + people enrichment, email finder, LinkedIn.

Available options:

lite,

standard,

deep

model

string

Override the synthesis model. Must match the provider's model ID (e.g. gpt-5, claude-opus-4.7, gemini-3.1-pro). Price adjusts automatically based on model cost.

schema

object

Optional flat field map for structured output. Keys are top-level result fields and values describe what each field should contain. This is not JSON Schema and does not support nested schema definitions. Example: { summary: 'Concise account summary', recommended_angles: 'Array of practical sales angles', risks: 'Array of deal risks' }.

Show child attributes

callback_url

string<uri>

Async mode. If provided, the API returns 202 immediately with a request_id and POSTs the full result to this URL when done. Useful for long-running deep research.

Response

Research completed synchronously.

success

boolean

Always true on 200.

request_id

string

Unique request identifier for logs and support. Status polling is available for async requests accepted with callback_url.

result

any

The research answer. String when no schema was provided. Object matching your schema keys when schema was provided — null fields mean not found.

data_source

enum<string>

Present on free-text responses. 'live' means the answer was grounded in current retrieved data; 'mixed' means current data plus stable model knowledge; 'model' means retrieval returned no usable data and the answer relies on model knowledge.

Available options:

live,

mixed,

model

confidence

object

Present on structured responses. Per-field source label: 'live', 'model', or 'not_found'. A not-found field is returned as null.

Show child attributes

tier

enum<string>

Tier used for this request, as resolved from the request body.

Available options:

lite,

standard,

deep

model

string

Synthesis model actually used (default for tier or your override).

price

number

Amount charged in USD for this request. Deducted from your balance.

credits_remaining

number

Your balance in USD after this request was charged.

Poll research status

⌘I