> ## 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. # 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. ## OpenAPI ````yaml /openapi.json post /research openapi: 3.0.3 info: title: Huntr — The GTM Intelligence API description: >- Give AI agents company, people, contact, and web intelligence through one API. Search accounts, build targeted lists, enrich leads, find contacts, and uncover buying signals. **Authentication:** Authenticated endpoints require an `x-api-key` header with your Huntr API key. Get a key by signing up via `POST /keys/create`. Public endpoints (pricing, sign-up, health) work without a key. **Rate limit:** 5 requests/second per API key on authenticated endpoints. version: 2.0.0 servers: - url: https://api.tryhuntr.com security: [] tags: - name: Research description: >- Research one company, person, team, or focused business question and return a sales-ready answer. Lite, standard, and deep tiers. - name: Companies description: >- Search companies and enrich firmographics. Per-result pricing on search; count endpoints are free. - name: People description: >- Search people and enrich contacts — work email, phone, and related lookup endpoints. - name: LinkedIn description: >- LinkedIn URL discovery, company and profile pages, posts, reactions, and comments. - name: X description: X profiles, posts, search results, and thread context. - name: Web description: >- Find and analyze pages on a domain, plus tech stack, domain contacts, and job postings. - name: Account description: >- Sign up, verify email, recover keys, check balance, view usage, add credits, and read the public pricing matrix. - name: System description: Health check. paths: /research: post: tags: - Research summary: Run a research task description: >- **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. requestBody: required: true content: application/json: schema: type: object required: - prompt properties: prompt: type: string description: >- The research question or task. Be specific about the context and output your workflow needs. tier: type: string enum: - lite - standard - deep default: standard description: >- 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. model: type: string description: >- 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: type: object description: >- 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' }. additionalProperties: type: string callback_url: type: string format: uri description: >- 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. examples: sync: summary: Account brief — free text value: 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 schema: summary: Structured account strategy value: prompt: >- We provide fraud-prevention APIs for fintech platforms and are building an account plan for Stripe. Research Stripe's enterprise product initiatives announced from June 2025 through June 2026, identify product or partnership angles where a fraud-prevention vendor could contribute, and flag risks that could stall a deal. tier: deep schema: summary: Concise account summary recommended_angles: Array of concrete product or partnership angles risks: Array of risks that could stall the deal async: summary: Async person brief value: prompt: >- We sell financial infrastructure software to internet businesses. Research Patrick Collison and the team he leads at Stripe. Summarize his current role, leadership priorities, public statements from June 2025 through June 2026, relevant company initiatives, and practical conversation angles. tier: deep callback_url: https://your-server.com/webhook responses: '200': description: Research completed synchronously. headers: X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current rate limit window. X-RateLimit-Reset: schema: type: integer description: >- Unix timestamp in milliseconds when the rate limit window resets. content: application/json: schema: type: object properties: success: type: boolean description: Always true on 200. request_id: type: string description: >- Unique request identifier for logs and support. Status polling is available for async requests accepted with callback_url. result: description: >- 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: type: string enum: - live - mixed - model description: >- 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. confidence: type: object description: >- Present on structured responses. Per-field source label: 'live', 'model', or 'not_found'. A not-found field is returned as null. additionalProperties: type: string enum: - live - model - not_found tier: type: string enum: - lite - standard - deep description: >- Tier used for this request, as resolved from the request body. model: type: string description: >- Synthesis model actually used (default for tier or your override). price: type: number description: >- Amount charged in USD for this request. Deducted from your balance. credits_remaining: type: number description: Your balance in USD after this request was charged. examples: freeText: summary: Free-text result value: 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 schema: summary: Structured result value: success: true request_id: req_1746123456_cd7y2m result: summary: Stripe is expanding enterprise payment infrastructure... recommended_angles: - Reduce fraud losses in platform payment flows risks: - Strong internal fraud tooling confidence: summary: live recommended_angles: live risks: live tier: deep model: gemini-2.5-flash price: 0.046 credits_remaining: 4.954 '202': description: >- Accepted — async mode. Research is running in the background. Poll GET /research/{requestId}/status until status is 'completed' or 'failed'. When finished, the full result is also POSTed to your callback_url as JSON: { request_id: string, success: boolean, result: string|object, tier: string, model: string, price: number, error: string|undefined }. content: application/json: schema: type: object properties: request_id: type: string description: >- Unique request identifier. Use this to poll GET /research/{requestId}/status. status: type: string enum: - running description: >- Always 'running' on 202 — research is accepted and in progress. poll_url: type: string description: >- Convenience full URL to poll for this request's status. Same as GET /research/{request_id}/status. tier: type: string enum: - lite - standard - deep description: Tier this request will run at. price: type: number description: >- Price charged for this request in USD. Credits are reserved up front and refunded automatically on failure. credits_remaining: type: number description: >- Your balance after the request price was reserved. Failed requests are refunded. example: request_id: req_1746123456_ef1z5p status: running poll_url: /research/req_1746123456_ef1z5p/status tier: deep price: 0.046 credits_remaining: 4.954 '400': description: >- Bad request — missing prompt, invalid model override, unsupported BYOK mode, invalid JSON, or unsafe callback URL. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Invalid or missing x-api-key header. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Insufficient credits. Top up via POST /topup then retry. content: application/json: schema: type: object properties: error: type: string description: Human-readable message. balance: type: number description: Your current balance in USD. price: type: number description: Price required for this request in USD. topup_hint: type: string description: How to add credits. example: error: Insufficient credits balance: 0.005 price: 0.027 topup_hint: 'POST /topup { "amount": 10 } to add credits' '422': description: >- The request requires bulk multi-entity enrichment outside the `/research` request budget. No credits are used. Follow the returned endpoint workflow to build and enrich the list. content: application/json: schema: type: object properties: success: type: boolean enum: - false code: type: string enum: - BULK_ENRICHMENT_REQUIRED message: type: string request_id: type: string price: type: number enum: - 0 credits_used: type: number enum: - 0 estimated_capability_cost_usd: type: number capability_budget_usd: type: number recommended_workflow: type: array items: type: object properties: endpoint: type: string purpose: type: string example: success: false code: BULK_ENRICHMENT_REQUIRED message: >- This request discovers multiple entities and performs paid enrichment for each. Use the dedicated list-building and enrichment endpoints. request_id: req_1746123456_bulk1 price: 0 credits_used: 0 recommended_workflow: - endpoint: /company-search purpose: Build a company list - endpoint: /person-search purpose: Find relevant people for each company - endpoint: /person-email purpose: Find an email for each selected person '429': description: Rate limit exceeded. Retry after the window resets. content: application/json: schema: type: object properties: error: type: string retry_after_seconds: type: integer description: >- Seconds until the rate limit window resets and you can retry. example: error: Rate limit exceeded retry_after_seconds: 42 '500': description: >- Agent error — triage or synthesis failed after retries. You are not charged. content: application/json: schema: type: object properties: error: type: string description: Error message describing what failed. credits_used: type: number description: Always 0 — no credits are deducted on a 500. example: error: Triage failed after 3 attempts credits_used: 0 security: - ApiKeyAuth: [] components: schemas: Error: type: object properties: error: type: string description: Human-readable error message. required: - error securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your Huntr API key. Get one at tryhuntr.com. Pass as x-api-key header on all authenticated requests. ````