> ## 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 one focused GTM research task and return a synthesized answer or structured result. Use direct search and enrichment endpoints for bulk workflows. ## 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: Contact APIs description: >- Search people and enrich work email, phone, and reverse-email contact fields. - name: Company APIs description: >- Search companies and retrieve company-level attributes such as detected technology stack and active job postings. - name: Research APIs description: >- Research one company, person, team, or focused business question and return a sales-ready answer. Lite, standard, and deep tiers. - name: LinkedIn APIs description: >- LinkedIn URL discovery, company and profile pages, posts, reactions, and comments. - name: X APIs description: X profiles, posts, search results, and thread context. - name: Web APIs description: >- Find, scrape, 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 APIs summary: Research Agent description: >- Run one focused GTM research task and return a synthesized answer or structured result. Use direct search and enrichment endpoints for bulk workflows. 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. Check `GET /pricing` for current tier and model prices. model: type: string description: >- Override the synthesis model. Must match the 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 company 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 required: - success - request_id - result - price - credits_remaining properties: success: type: boolean request_id: type: string result: type: object required: - output - tier - model properties: output: oneOf: - title: Text answer description: Plain-text or markdown research output. type: string - title: Structured object description: >- Object output when the request asks for structured fields. type: object additionalProperties: true - title: Structured array description: >- Array output when the request asks for a list-shaped result. type: array items: {} confidence: type: object nullable: true additionalProperties: type: string data_source: type: string description: Present when confidence is not available. tier: type: string enum: - lite - standard - deep model: type: string additionalProperties: false price: type: number credits_remaining: type: number additionalProperties: false examples: freeText: summary: Free-text research result value: success: true request_id: req_1746123456_ab3x9k result: output: >- Shells current cloud-efficiency priorities include workload modernization, lower unit infrastructure cost, and better governance for AI workloads. confidence: level: medium reason: >- Based on current public sources found during the request. tier: deep model: gemini-2.5-flash price: 0.046 credits_remaining: 4.954 schema: summary: Structured research result value: success: true request_id: req_1746123456_cd7y2m result: output: summary: Stripe is expanding enterprise payment infrastructure. recommended_angles: - Fraud prevention for high-risk payment flows risks: - Existing in-house risk tooling data_source: 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 required: - success - request_id - result - price - credits_remaining properties: success: type: boolean request_id: type: string result: type: object required: - status - poll_url - tier - model properties: status: type: string enum: - running poll_url: type: string tier: type: string enum: - lite - standard - deep model: type: string additionalProperties: false price: type: number credits_remaining: type: number additionalProperties: false examples: async: summary: Async research accepted value: success: true request_id: req_1746123456_ef1z5p result: status: running poll_url: /research/req_1746123456_ef1z5p/status tier: deep model: gemini-2.5-flash 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: [] x-codeSamples: - lang: Shell label: cURL source: |- curl --request POST \ --url https://api.tryhuntr.com/research \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --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, 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" }' x-code-samples: - lang: Shell label: cURL source: |- curl --request POST \ --url https://api.tryhuntr.com/research \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --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, 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" }' 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.