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
}

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.