Research

The Ideas Engine uses research under the hood, but you can also call it directly. POST /v1/research starts an async research run; poll the returned run_id until it completes.

Base URL: https://agent.gen.pro/v1

Trigger research

curl -X POST "https://agent.gen.pro/v1/research" \
  -H "X-API-Key: $GEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'"$AGENT_ID"'",
    "topic": "tariffs on beauty imports 2026",
    "depth": "default"
  }'

Parameters

Field	Type	Required	Description
agent_id	string	Yes	Scope research to this agent.
topic	string	Yes	The subject to research.
depth	string	No	quick (fast, surface-level), default, or deep (slower, thorough). Defaults to default.

Response (202)

{
  "run_id": "run_abc",
  "conversation_id": "conv_xyz",
  "status": "running",
  "firebase_path": "..."
}

Poll GET /v1/agent/runs/{run_id} until status is completed. The completed run messages contain the structured research findings and summary.

When to call research directly

• You want fresh source signals to drive your own idea generation pipeline
• You need sources for a specific claim
• You want to build a research digest email or Slack post

Note

Research is a paid operation (web_research credit type, ~35 credits). The Ideas Engine automatically runs research when the agent decides it needs fresh data; calling /v1/research directly gives you the same signal without generating ideas on top.

Research is daily on configured topics

If you set research_topics on Agent Core, the platform automatically researches each topic daily and feeds the findings into the agent’s Ideas Engine on the next run. No polling needed — just set the topics and consume the ideas downstream.

{
  "research_topics": [
    { "topic": "new food truck openings in San Antonio" },
    { "topic": "viral street food TikTok moments" }
  ]
}

See Agent Core — research_topics for how to configure them.