Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thehog.ai/llms.txt

Use this file to discover all available pages before exploring further.

Deep research lets you ask open-ended research questions and receive structured, schema-conformant answers. You describe what you want to know in a natural language prompt, define the exact shape of the data you need as a JSON Schema, and The Hog browses the web, synthesizes findings with an LLM, and returns a result that matches your schema precisely. This is useful for building account intelligence, competitive analysis, market mapping, and any task that requires gathering information from multiple web sources and transforming it into structured data.
Deep research is always asynchronous. The endpoint returns HTTP 202 immediately with an operationId. Depending on the complexity of your prompt and schema, results typically arrive within 1–5 minutes. Poll GET /api/operations/:id until status is "succeeded".

​
Endpoint

POST https://api.thehog.ai/api/deep-research

​
Request fields

FieldTypeRequiredDescription
promptstringYesNatural language research question or instruction
schemaobjectYesJSON Schema that defines the structure of the result you want back
modelstringNoOverride the default model (e.g. "openai:gpt-4.1")
urlsstring[]NoOptional seed URLs to include as starting points for research
projectIdstringNoProject context for brand-aware research (can also be set via X-Project-Id header)

​
Idempotency

Include an Idempotency-Key header to prevent duplicate jobs. If you submit the same key twice within the deduplication window, the second request returns the existing queued operation instead of starting a new one. 
Idempotency-Key: your-unique-key-here

​
Examples

curl -X POST https://api.thehog.ai/api/deep-research \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: research-acme-2026-05" \
  -d '{
    "prompt": "Research Acme Corp (acme.com). Find their main products, target customers, recent funding announcements, key executives, and any recent press coverage from the last 6 months.",
    "schema": {
      "type": "object",
      "properties": {
        "companyName": { "type": "string" },
        "mainProducts": {
          "type": "array",
          "items": { "type": "string" }
        },
        "targetCustomers": { "type": "string" },
        "recentFunding": {
          "type": "object",
          "properties": {
            "amount": { "type": "string" },
            "round": { "type": "string" },
            "date": { "type": "string" }
          }
        },
        "keyExecutives": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "title": { "type": "string" }
            }
          }
        },
        "recentPress": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "headline": { "type": "string" },
              "source": { "type": "string" },
              "date": { "type": "string" }
            }
          }
        }
      },
      "required": ["companyName", "mainProducts", "targetCustomers"]
    },
    "urls": ["https://acme.com", "https://techcrunch.com"]
  }'

​
Accepted response (HTTP 202)

{
  "id": "op_01hxyz",
  "operationId": "op_01hxyz",
  "status": "queued",
  "pollUrl": "/api/operations/op_01hxyz"
}

​
Polling for results

Poll GET /api/operations/:id until status is "succeeded" or "failed". 
curl https://api.thehog.ai/api/operations/op_01hxyz \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Steps to run deep research

1

Write a focused prompt

Be specific about what you want to learn and from what time window. Narrow prompts produce more accurate structured results than broad open-ended ones.
2

Define your JSON Schema

Design the schema to match exactly the fields you need downstream. Use required to mark fields that must always be present. The result will conform to this schema.
3

Submit with an Idempotency-Key

Use a deterministic key (e.g. research-{company}-{month}) so that retries or duplicate submissions return the same operation instead of spawning redundant jobs.
4

Store the operationId and poll

Save the operationId from the 202 response. Poll every 10–30 seconds until status is "succeeded". For production use, implement exponential backoff.
5

Consume the structured result

The result field in the completed operation matches your JSON Schema exactly, so you can map it directly into your data pipeline or CRM.
Deep research jobs consume credits proportional to the complexity of the prompt and the number of web sources queried. Use specific prompts and targeted urls to keep costs predictable. The Idempotency-Key header ensures you are not charged twice for duplicate submissions.