Research

# Research

Get comprehensive, multi-source answers to complex questions -- with citations, saved as documents you can reference anytime.

## When to Use
- User wants in-depth research on a topic, competitor, or market trend
- User needs multi-source research with citations (council mode uses multiple providers)
- User wants to monitor a website or topic for changes over time
- User is doing competitive analysis or market research before making decisions
- User wants research findings saved for future reference

## How It Connects
- **Documents** -> Research results are automatically saved as document pages. Access them anytime.
- **Blog** -> Use research findings to inform and substantiate blog articles.
- **Branding** -> Research competitors to refine brand positioning and unique attributes.
- **SEO** -> Research can inform keyword strategy and content gap analysis.
- **Tasks** -> Propose research tasks for human review before running expensive queries.

## Quick Start

Run deep research on a topic:
```bash
clawpow research deep --query "AI agent frameworks comparison 2025" --json
```

## Commands

### Deep Research
```bash
clawpow research deep --query "<query>" --json
clawpow research deep --query "<query>" --summarize --json
clawpow research deep --query "<query>" --council --json
clawpow research deep --query "<query>" --providers perplexity/sonar-deep-research,openai/o4-mini-deep-research --summarize --json
```
Run deep research on a topic. Each provider runs independently and produces its own document. Optionally summarize the results into a single synthesis document.

Returns immediately with a research ID -- poll with `research get` to check completion and see per-provider status.

**Options:**
- `--query <text>` (required) -- Research topic or question
- `--provider <model>` -- Provider model ID for single-provider research (default: perplexity/sonar-deep-research)
- `--summarize` -- Generate a synthesis summary document after all providers complete
- `--council` -- Use all registered providers with summary enabled. The provider list is managed server-side and may change as models are added or removed.
- `--providers <list>` -- Comma-separated list of provider model IDs (e.g. `perplexity/sonar-deep-research,o4-mini-deep-research,parallel:ultra`). Implies multi-provider mode.
- `--json` -- Output as JSON

**Returns:** `{"researchId": "...", "status": "researching", "studioUrl": "...", "nextCommand": "clawpow research get <researchId>"}`

Results are saved as document pages. Use `clawpow research get <researchId> --json` to check per-provider status and find document IDs. If `--summarize` was used, the `summaryDocId` field will contain the synthesis document once all providers complete. Read individual results or the summary with `clawpow documents pages get <docId> --json`.

### List Research
```bash
clawpow research list --json
```
List all deep research jobs.

**Options:**
- `--status <status>` -- Filter: queued, running, succeeded, failed
- `--limit <n>` -- Max results (default: 20)
- `--json` -- Output as JSON

**Returns:** Array of `{_id, query, mode, status, providers, summarize, providerResults, summaryDocId, _creationTime}`

### Get Research
```bash
clawpow research get <researchId> --json
```
Get a research job, its per-provider status, and result document IDs.

**Options:**
- `<researchId>` (required, positional) -- Research job ID
- `--content` -- Include document content for each provider result and summary
- `--json` -- Output as JSON

**Returns:**
```json
{
  "_id": "...",
  "query": "...",
  "mode": "single|council",
  "status": "queued|running|succeeded|failed",
  "providers": ["perplexity/sonar-deep-research", "..."],
  "summarize": true,
  "providerResults": [
    {"provider": "perplexity/sonar-deep-research", "status": "succeeded", "docId": "...", "content": "..."},
    {"provider": "openai/o4-mini-deep-research", "status": "running"}
  ],
  "summaryDocId": "...",
  "summaryContent": "...",
  "studioUrl": "...",
  "error": null,
  "_creationTime": 1234567890
}
```

The `providerResults` array shows the status of each provider individually (`pending`, `running`, `succeeded`, `failed`). When a provider succeeds, its `docId` points to the research document. With `--content`, the `content` field contains the document body inline and `summaryContent` contains the summary document body. The top-level `summaryDocId` is populated once all providers complete and the summary is generated (only when `--summarize` or `--council` was used).

### Create Monitor
```bash
clawpow research monitor create "<query>" --cadence daily --json
```
Create a web monitor that automatically tracks a topic. Parallel.ai checks the web at the configured cadence and pushes events when new findings are detected.

**Options:**
- `<query>` (required, positional) -- Topic to monitor
- `--cadence <interval>` -- Check frequency: hourly, every_6h, daily, weekly (default: daily)
- `--json` -- Output as JSON

**Returns:** `{"monitorId": "...", "status": "active"}`

### List Monitors
```bash
clawpow research monitor list --json
```
List all monitors.

**Options:**
- `--status <status>` -- Filter: active, inactive
- `--json` -- Output as JSON

**Returns:** Array of `{_id, query, cadence, status, lastCheckedAt, checkCount, _creationTime}`

### Deactivate Monitor
```bash
clawpow research monitor off <monitorId> --json
```
Deactivate an active monitor. It will not run scheduled checks until reactivated.

**Returns:** `{"monitorId": "...", "status": "inactive"}`

### Activate Monitor
```bash
clawpow research monitor on <monitorId> --json
```
Reactivate a deactivated monitor.

**Returns:** `{"monitorId": "...", "status": "active"}`

### List Monitor Events
```bash
clawpow research monitor events <monitorId> --json
clawpow research monitor events <monitorId> --limit 10 --json
```
List events detected by a monitor. Events are returned newest-first.

**Options:**
- `<monitorId>` (required, positional) -- Monitor ID
- `--limit <n>` -- Max results (default: 25)
- `--json` -- Output as JSON

**Returns:** Array of `{_id, monitorId, eventGroupId, content, eventDate, sourceUrls, eventType, error, _creationTime}`

- `eventType` is one of: `event` (new finding), `error` (check failed), `completion` (check cycle finished)
- `sourceUrls` contains the URLs where the finding was detected
- `eventDate` is the date string reported by the source (may be absent)

### Delete Monitor
```bash
clawpow research monitor delete <monitorId> --json
```
Delete a monitor permanently.

**Returns:** `{"monitorId": "...", "deleted": true}`

## Output Format

All commands support `--json` for structured output. Without `--json`, output is human-readable.

## Important Notes

- Always use `--json` for machine-parseable output
- Deep research is async — it returns immediately and runs in the background
- Use `clawpow research get <researchId> --json` to poll for completion (check `status` field)
- Deep research is a paid operation (consumes credits)
- Monitor creation, listing, activating, deactivating, and deleting are free operations
- Research results are saved as document pages — read them with `clawpow documents pages get <docId> --json`
- Each provider runs independently and produces its own document -- check `providerResults` for per-provider progress
- Use `--summarize` to get a single synthesis document after all providers finish
- `--council` is shorthand for multi-provider with summary enabled (provider list managed server-side)
- Providers that take longer than 15 minutes are automatically timed out
- Monitors automatically check at the configured cadence via cron jobs
- Valid cadence values: hourly, every_6h, daily, weekly
- Monitors use Parallel.ai to track the web — events are pushed via webhook when new findings are detected
- Monitor creation is free; each check cycle costs $0.003 (billed automatically)