Deep Research Agent API

GET/health

Health check endpoint.

Response

{ "ok": true, "service": "deep-research-agent" }

GET/research/:responseId

Resume polling for a background deep research job. Use this to check on jobs that failed due to rate limits or timeouts.

Path Parameters

Parameter	Description
responseId	The response_id returned from the initial POST /research call (e.g., resp_abc123)

Authentication

Requires X-API-Key header.

Behavior

• If the job is completed: Returns the full answer immediately
• If the job is in_progress/queued: Polls until complete (max 30 min)
• If the job failed: Returns error details
• If rate limited during polling: Returns with instructions to retry later

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://deep-research-agent.vetapp.workers.dev/research/resp_abc123"

Response

{
  "ok": true,
  "answer": "...",
  "response_id": "resp_abc123",
  "mode": "deep_research",
  "raw_response": { ... },
  "trace": [ ... ]
}

POST/research

Execute a deep research query with multi-round web search, fact extraction, and validated synthesis.

Request Body

Field	Type	Description
questionrequired	string	The research question to answer
optionsoptional	object	Configuration overrides (see below)

Model Options

Option	Type	Default	Description
model	string	"gpt-4o-mini"	OpenAI model (o3-deep-research, o4-mini-deep-research, gpt-5.2, gpt-4.1, gpt-4o, o3, etc.)
temperature	number	null	Sampling temperature (0-2)
top_p	number	null	Nucleus sampling (0-1)
max_output_tokens	number	null	Max tokens to generate (1-128000)
reasoning_effort	string	null	For o1/o3 models: "low", "medium", or "high"
instructions	string	null	System instructions/prompt
store	boolean	true	Whether to store response in OpenAI
maxRetries	number	3	Max retry attempts for failed API calls (0-5)

Deep Research Options (o3-deep-research, o4-mini-deep-research)

Option	Type	Default	Description
background	boolean	false	Run in background mode (recommended for long tasks)
codeInterpreter	boolean	false	Enable Python code execution for data analysis
maxToolCalls	number	null	Max tool calls before returning (1-1000)
reasoningSummary	string	null	Reasoning summary: "auto", "concise", or "detailed"

Deep research models can analyze hundreds of sources and take 10-30+ minutes. Use background mode to prevent timeouts.

Research Agent Options

Option	Type	Default	Description
maxSearchRounds	number	4	Max search iterations (1-10)
maxFacts	number	18	Max facts to collect (5-50)
minNewFactsPerRound	number	2	Min new facts per round before stagnation (0-10)

Web Search Options

Option	Type	Default	Description
webContextSize	string	"medium"	Search depth: "low", "medium", or "high"
forceDomains	array	null	Restrict sources to specific domains (e.g., [".gov", ".edu"])
userLocation	object	null	Location for localized results (see below)

User Location Object

Field	Type	Description
country	string	ISO 2-letter country code (e.g., "US", "GB")
city	string	City name (e.g., "San Francisco")
region	string	State/region (e.g., "California")
timezone	string	IANA timezone (e.g., "America/Los_Angeles")

Authentication

This endpoint requires an API key. Include it in the X-API-Key header.

Example Request

curl -X POST "https://deep-research-agent.vetapp.workers.dev/research" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "question": "What is the OpenAI Responses API?",
    "options": {
      "model": "gpt-4o",
      "temperature": 0.7,
      "maxSearchRounds": 3,
      "maxFacts": 12,
      "webContextSize": "medium",
      "forceDomains": ["openai.com", ".edu"],
      "userLocation": { "country": "US" }
    }
  }'

Response

Field	Description
ok	Success boolean
question	Original question
answer	Synthesized answer with [F#] citations
fact_table	Array of extracted facts with URLs, confidence, and quality scores
conflicts	Detected conflicting claims between sources
plan	Research plan with queries and stop conditions
validation	Validation results and any issues found
trace	Execution trace for debugging
startedAt / finishedAt	Timestamps