> ## 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.
# Run Deep Research with LLM-Powered Analysis
> Submit a research prompt and JSON Schema to The Hog's deep research endpoint. Get back structured data matching your schema, extracted from web sources.
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
```text theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://developer.thehog.ai/api/deep-research
```
## Request fields
| Field | Type | Required | Description |
| -------- | --------- | -------- | ------------------------------------------------------------------ |
| `prompt` | string | Yes | Natural language research question or instruction |
| `schema` | object | Yes | JSON Schema that defines the structure of the result you want back |
| `model` | string | No | Override the default model (e.g. `"openai:gpt-4.1"`) |
| `urls` | string\[] | No | Optional seed URLs to include as starting points for research |
### 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.
```text theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
Idempotency-Key: your-unique-key-here
```
***
## Examples
```bash Start a deep research job theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://developer.thehog.ai/api/deep-research \
-H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-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"]
}'
```
```bash With seed URLs and model override theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://developer.thehog.ai/api/deep-research \
-H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"prompt": "What are the top 5 CRM tools used by mid-market B2B SaaS companies in 2026? For each, note market share, pricing model, and key differentiator.",
"schema": {
"type": "object",
"properties": {
"tools": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"marketShare": { "type": "string" },
"pricingModel": { "type": "string" },
"keyDifferentiator": { "type": "string" }
},
"required": ["name"]
}
}
},
"required": ["tools"]
},
"model": "openai:gpt-4.1"
}'
```
### Accepted response (HTTP 202)
```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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"`.
```bash Poll the operation theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://developer.thehog.ai/api/operations/op_01hxyz \
-H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"
```
```json In-progress response theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "op_01hxyz",
"status": "processing",
"progress": 45,
"result": null,
"error": null
}
```
```json Completed response theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "op_01hxyz",
"status": "succeeded",
"progress": 100,
"result": {
"companyName": "Acme Corp",
"mainProducts": ["Acme Cloud", "Acme Analytics"],
"targetCustomers": "Mid-market B2B SaaS companies with 50–500 employees",
"recentFunding": {
"amount": "$42M",
"round": "Series B",
"date": "2026-02"
},
"keyExecutives": [
{ "name": "Casey Nguyen", "title": "CEO" },
{ "name": "Jordan Rivera", "title": "CTO" }
],
"recentPress": [
{
"headline": "Acme Corp Raises $42M to Expand AI-Powered Analytics",
"source": "TechCrunch",
"date": "2026-02-14"
}
]
},
"error": null
}
```
***
## Steps to run deep research
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.
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.
Use a deterministic key (e.g. `research-{company}-{month}`) so that retries or duplicate submissions return the same operation instead of spawning redundant jobs.
Save the `operationId` from the 202 response. Poll every 10–30 seconds until `status` is `"succeeded"`. For production use, implement exponential backoff.
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.