Web Agent

`POST https://api.keirolabs.cloud/api/webagents/research/stream`

Cost: 7 credits + 1 per 1k tokens · Latency: Streams

Autonomous research agent that streams formatted markdown, validates facts, and returns structured data via Server-Sent Events (SSE).

**When to use it.** Use when you want an agentic system that streams its thought process, fact checks, and outputs multiple structured components like timelines and tables.

**When not to.** Do not use if you only need a quick SERP or a single extracted article.

## Request

**cURL**

```bash
curl -N -X POST https://api.keirolabs.cloud/api/webagents/research/stream \
  -H "Authorization: Bearer $KEIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Compare React 19 and Vue 3.5 for a large dashboard", "research_depth": "medium", "outputs": ["summary", "sources"]}'
```

**Python**

```python
import os, requests

res = requests.post(
    "https://api.keirolabs.cloud/api/webagents/research/stream",
    headers={"Authorization": f"Bearer {os.environ['KEIRO_API_KEY']}"},
    json={
        "query": "Compare React 19 and Vue 3.5 for a large dashboard",
        "research_depth": "medium",
        "outputs": [
            "summary",
            "sources"
        ]
    },
    stream=True,
)
for line in res.iter_lines():
    print(line.decode())
```

**Node.js**

```js
const res = await fetch("https://api.keirolabs.cloud/api/webagents/research/stream", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KEIRO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "query": "Compare React 19 and Vue 3.5 for a large dashboard",
    "research_depth": "medium",
    "outputs": [
      "summary",
      "sources"
    ]
  }),
});
for await (const chunk of res.body) process.stdout.write(chunk);
```

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | The topic to research. |
| `research_depth` | string | no | low \| medium \| high. Default: medium |
| `research_mode` | string | no | auto \| academic \| financial \| compare \| fact_check |
| `outputs` | array | no | Array of expected outputs (e.g., ["summary", "detailed_answer", "claims", "sources", "table", "timeline", "premise_validation"]) |

## Response

```json title="200 OK"
{
  "type": "chunk",
  "section": "summary",
  "data": "React is a UI library backed by Meta. Vue is a progressive framework...",
  "metadata": {
    "token_usage": {
      "total_tokens": 15420
    }
  }
}
```

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | no | Event type ("start", "chunk", "error", "done"). |
| `section` | string | no | The output section being streamed (e.g. "summary", "timeline"). |
| `data` | string/object | no | The chunk content (string for markdown, object for JSON arrays like timeline). |
| `metadata` | object | no | Available on "done" event. Contains token_usage and credits. |

## Other routes

- `POST /api/webagents/research`: Non-streaming (synchronous) version. Wait for the entire task to complete and return a single JSON object. Use this for automated background processing where real-time UI updates are not needed.

## Errors

| Status | Code | Cause | Fix |
| --- | --- | --- | --- |
| `400` | `VALIDATION_ERROR` | Missing query | Provide a query. |
| `401` | `UNAUTHORIZED` | Missing or invalid API key | Check your Authorization header. |

## Rate limits

| Tier | Limit |
| --- | --- |
| Free | 3/min |
| Starter | 10/min |
| Pro | 20/min |
| Startup | 40/min |
| Enterprise | 80/min |

Over the limit you get a `429`. See [Rate limits](/rate-limits) for headers and backoff.