Research Agent API

POST /research

Run a deep research query with web search, news, and scraping. Returns structured or free-text output. Costs 1-6 credits depending on the model.

Parameters (query string or JSON body)

Accepts both query string params and JSON body. Use JSON body for long prompts and schemas (query strings have URL length limits).

prompt	Required. The research instruction.
model	OpenRouter model ID. Included: google/gemini-3.1-flash-lite (default), google/gemini-3.5-flash, google/gemini-2.5-flash-lite, google/gemini-2.5-flash. With BYOK: any OpenRouter model.
schema	JSON schema for structured output. Accepts a JSON object or a JSON string.
depth	Research depth: quick (fast, 1-3 tools, ~45s), standard (default, balanced), or deep (thorough, 8-15 tools, up to 5min).
max_iterations	Override max agent iterations (1-50). Overrides depth preset if both are set.
temperature	0.0-2.0. Default: 0.1

Headers

X-Auth-Token	Required. Your API key.
X-OpenRouter-API-Key	Optional. BYOK — use any model. Scale plan: no credits deducted.

# Quick lookup — minimal params
curl -X POST "https://research-agent.net/research" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What does Stripe do and how many employees do they have?",
    "depth": "quick"
  }'

# Full example — all params
curl -X POST "https://research-agent.net/research" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Research Stripe Inc. Find their ICP, tech stack, total funding, and recent news.",
    "model": "google/gemini-2.5-flash",
    "depth": "deep",
    "max_iterations": 35,
    "temperature": 0.1,
    "schema": {
      "type": "object",
      "properties": {
        "company": { "type": "string", "description": "Company name" },
        "icp": { "type": "string", "description": "Ideal customer profile" },
        "tech_stack": { "type": "array", "items": { "type": "string" } },
        "funding_total": { "type": "string", "description": "Total funding raised" },
        "recent_news": { "type": "array", "items": { "type": "string" } }
      }
    }
  }'

Response

{
  "output": {
    "company": "Stripe",
    "icp": "Internet businesses needing payment infrastructure...",
    "tech_stack": ["Ruby", "Go", "React", "AWS"],
    "funding_total": "$8.7B",
    "recent_news": ["Stripe launches new billing product..."]
  },
  "model_used": "google/gemini-2.5-flash",
  "execution_time_seconds": 42.1
}

POST /build-list

Turn just an ICP into a verified account or lead list. The agent finds real, ICP-matched companies (or companies + a decision-maker), researches each one live across the web and LinkedIn, and returns validated JSON rows. Batches to reach your target count, deduped by domain. Billed per returned row (only successful rows — 0 rows = free).

Parameters (JSON body)

icp	Required. Free-text description of your ideal customer profile.
list_type	accounts (companies, default) or leads (companies + a decision-maker with role & LinkedIn URL).
count	Target number of rows, 1–5000. Default 20. Billed per returned row (credits_per_row in the response); if your balance is lower, the list is auto-capped to what you can afford and flagged via capped_to_balance.
columns	Optional array of extra research questions filled per row, e.g. ["who they sell to","open sales roles"].
region	Optional region / market constraint, e.g. DACH.
model	OpenRouter model ID. Default google/gemini-3.1-flash-lite. Higher-quality lists: google/gemini-2.5-flash.
qualify	Default true. Runs a second, conservative ICP-qualification pass that drops off-ICP rows (the response reports how many via qualified_out). Set false to keep every candidate.
max_iterations	Optional per-batch agent iteration cap.

Headers

X-Auth-Token	Required. Your API key.
X-OpenRouter-API-Key	Optional. BYOK — use any model. Scale plan: no credits deducted.

# Build a 25-lead list from an ICP
curl -X POST "https://research-agent.net/build-list" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "icp": "B2B SaaS companies in DACH selling sales or marketing software to mid-market (50-250 employees)",
    "list_type": "leads",
    "count": 25,
    "region": "DACH",
    "columns": ["who they sell to", "any open sales roles"]
  }'

Response

{
  "count": 25,
  "requested": 25,
  "list_type": "leads",
  "model_used": "google/gemini-2.5-flash",
  "credits_charged": 50,
  "results": [
    {
      "company": "Dealfront",
      "domain": "dealfront.com",
      "icp_match": true,
      "icp_match_reason": "DACH-based B2B SaaS, ~250 employees, sales/marketing software.",
      "description": "B2B sales intelligence and lead-gen platform.",
      "person_name": "Mike Dry",
      "role": "VP of Customer Success",
      "linkedin_url": "https://www.linkedin.com/in/mikedry/",
      "who_they_sell_to": "B2B sales and marketing teams",
      "any_open_sales_roles": "",
      "source_urls": ["https://www.dealfront.com", "https://www.linkedin.com/in/mikedry/"]
    }
  ]
}

GET /agents

List all your agents.

Response

{ "agents": [{ "id": "uuid", "name": "...", "model": "...", "input_variables": [...], "is_active": true, ... }] }

POST /agents

Create a new agent.

Request body (JSON)

{
  "name": "Company Enrichment",
  "description": "Enrich company data",
  "prompt_template": "Research {{company_name}} at {{website}} and find their ICP, tech stack, and funding.",
  "input_variables": ["company_name", "website"],
  "model": "google/gemini-2.5-flash",
  "temperature": 0.1,
  "output_schema": null
}

GET /agents/{agent_id}

Get agent details by ID.

PUT /agents/{agent_id}

Update agent configuration. Only provided fields are changed.

DELETE /agents/{agent_id}

Permanently delete an agent.

POST /agents/{agent_id}/run

Execute an agent with input variables. Costs the agent's per-model credits (1-6).

Request body (JSON) — input variables + optional depth/max_iterations

# Standard depth (default)
{ "company_name": "Stripe", "website": "https://stripe.com" }

# Quick lookup
{ "company_name": "Stripe", "website": "https://stripe.com", "depth": "quick" }

# Deep research
{ "company_name": "Stripe", "website": "https://stripe.com", "depth": "deep" }

Response

{
  "agent_id": "uuid",
  "agent_name": "Company Enrichment",
  "output": { "icp": "...", "tech_stack": [...] },
  "execution_time_seconds": 12.5,
  "request_id": "A1B2C3D4"
}

GET /agents/{agent_id}/runs

List past runs for an agent.

Query parameters

limit

Max results (default 50, max 200)

GET /agents/templates

List available pre-built agent templates. Each template comes in lean (quick) and standard variants.

POST /agents/{agent_id}/bulk-run

Submit a bulk run job. Costs the agent's per-model credits per item. Max 1000 items.

Request body (JSON)

{
  "items": [
    { "company_name": "Stripe", "website": "https://stripe.com" },
    { "company_name": "Notion", "website": "https://notion.so" },
    { "company_name": "Linear", "website": "https://linear.app" }
  ],
  "depth": "deep"
}

Response

{
  "job_id": "uuid",
  "total_items": 3,
  "status": "running"
}

GET /agents/{agent_id}/bulk-runs

List all bulk run jobs for an agent. Returns job_id, status, progress counts, timestamps.

GET /agents/{agent_id}/bulk-runs/{job_id}

Get bulk job status and progress.

Response

{
  "id": "uuid",
  "agent_id": "uuid",
  "status": "running",
  "total_items": 100,
  "completed_items": 45,
  "failed_items": 2,
  "created_at": "2026-03-04T12:00:00Z",
  "completed_at": null
}

GET /agents/{agent_id}/bulk-runs/{job_id}/results

Get individual item results (paginated).

Query parameters

offset	Skip N items (default 0)
limit	Max items to return (default 50, max 100)

Response

{
  "job_id": "uuid",
  "offset": 0,
  "items": [
    {
      "id": "uuid",
      "input_variables": { "company_name": "Stripe", "website": "https://stripe.com" },
      "status": "completed",
      "output": { "icp": "...", "tech_stack": [...] },
      "execution_time_seconds": 11.2
    }
  ]
}

DELETE /agents/{agent_id}/bulk-runs/{job_id}

Cancel a running bulk job. Completed items are kept.

GET /billing/credits

Get current credit balance and recent transactions.

GET /billing/plans

List available credit packs with prices.

POST /billing/checkout

Create a Stripe checkout session to purchase credits.

GET /auth/me

Get current user identity.

{ "id": "uuid", "email": "user@example.com", "display_name": "John", "created_at": "..." }

GET /auth/usage

Get usage statistics.

days	Lookback period in days (default 30)

POST /auth/rotate-key

Regenerate your API key. Old key is deactivated.