Quickstart

Get started with Helix Deep Research in under 5 minutes. This guide walks you through creating your first research task, streaming real-time progress, and retrieving the completed report.

Prerequisites

Before you begin, you'll need:

A Helix API key (see Authentication)
A command-line terminal or API client

Step 1: Create a Research Task

Submit a research topic to start the multi-agent research process:

curl -X POST https://api.feeds.onhelix.ai/research/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "What are the latest advancements in solid-state battery technology and their implications for electric vehicles?",
    "detail": "basic"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "running",
    "input": "What are the latest advancements in solid-state battery technology and their implications for electric vehicles?",
    "detail": "basic",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "completedAt": null,
    "streamUrl": "/research/tasks/550e8400-e29b-41d4-a716-446655440000/stream"
  }
}

Save the id and streamUrl values — you'll need them to stream results and retrieve the final report.

What happens next?

A supervisor agent breaks your topic into sub-topics
Multiple sub-researcher agents work in parallel, searching the web and extracting content
Sources are collected and analyzed
A comprehensive report with citations is synthesized

Step 2: Stream Results in Real-Time

Connect to the SSE stream to watch research progress as it happens:

curl -N "https://api.feeds.onhelix.ai/research/tasks/550e8400-e29b-41d4-a716-446655440000/stream" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example SSE output:

event: topic
data: {"topic":"solid-state-battery-materials","index":1,"status":"started"}

event: source
data: {"url":"https://example.com/solid-state-research","title":"Solid-State Battery Breakthroughs","topic":"solid-state-battery-materials"}

event: progress
data: {"topics_total":3,"topics_completed":1,"sources_found":5}

event: topic
data: {"topic":"solid-state-battery-materials","index":1,"status":"completed"}

event: result
data: {"report":"# Solid-State Battery Technology...","topics_researched":["solid-state-battery-materials","ev-integration","manufacturing-challenges"],"sources":[...],"sub_reports_count":3,"confidence_level":"high"}

event: done
data: {}

The stream ends with a done event when the research is complete, or an error event if something went wrong.

Step 3: Retrieve the Completed Result

Once the research is complete, you can retrieve the full result at any time:

curl "https://api.feeds.onhelix.ai/research/tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (when complete):

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "input": "What are the latest advancements in solid-state battery technology and their implications for electric vehicles?",
    "detail": "basic",
    "result": {
      "report": "# Solid-State Battery Technology and Electric Vehicles\n\n## Overview\n\nSolid-state batteries represent a significant advancement...",
      "topics_researched": [
        "solid-state-battery-materials",
        "ev-integration",
        "manufacturing-challenges"
      ],
      "sources": [
        {
          "url": "https://example.com/solid-state-research",
          "title": "Solid-State Battery Breakthroughs"
        }
      ],
      "sub_reports_count": 3,
      "confidence_level": "high"
    },
    "usage": {
      "sub_researchers": 3,
      "sources_analyzed": 12
    },
    "createdAt": "2025-01-15T10:30:00.000Z",
    "completedAt": "2025-01-15T10:35:42.000Z",
    "streamUrl": "/research/tasks/550e8400-e29b-41d4-a716-446655440000/stream"
  }
}

Understanding the Results

The research task response includes a full report with supporting data:

Result fields:

report — The comprehensive research report in Markdown format
topics_researched — List of sub-topics that were investigated
sources — Web sources discovered and cited in the report
sub_reports_count — Number of sub-reports that were synthesized
confidence_level — Overall confidence in the research quality (high, medium, low)

Usage fields:

sub_researchers — Number of sub-researcher agents that ran
sources_analyzed — Total number of web sources analyzed

Detail levels (detail parameter):

basic — Default. SSE stream includes high-level progress events (topics, sources, progress, result)
detailed — SSE stream includes additional agent-level events (agent lifecycle, tool calls, LLM text generation, reasoning). Useful for debugging and developer tools

See the Overview for detailed explanations.

Next Steps

Now that you've completed your first research task, you can:

Learn the architecture: Understand how the multi-agent system works in the Overview
Stream with detail: Use the Streaming Guide to build real-time UIs
Explore the API: See all endpoints in the API Reference

Common Patterns

Polling Fallback

If you prefer polling over streaming:

# Check status every 10 seconds until complete
while true; do
  STATUS=$(curl -s "https://api.feeds.onhelix.ai/research/tasks/550e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer YOUR_API_KEY" | jq -r '.data.status')

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    break
  fi

  sleep 10
done

JavaScript with EventSource

const taskId = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://api.feeds.onhelix.ai/research/tasks/${taskId}/stream`;

const eventSource = new EventSource(url, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});

eventSource.addEventListener('progress', (e) => {
  const data = JSON.parse(e.data);
  console.log(
    `Progress: ${data.topics_completed}/${data.topics_total} topics, ${data.sources_found} sources`
  );
});

eventSource.addEventListener('result', (e) => {
  const data = JSON.parse(e.data);
  console.log('Report:', data.report);
});

eventSource.addEventListener('done', () => {
  eventSource.close();
});

eventSource.addEventListener('error', (e) => {
  console.error('Stream error:', e.data);
  eventSource.close();
});

Reconnecting with Snapshots

If your page refreshes or connection drops during a long-running task, use the snapshot endpoint to instantly restore state instead of replaying all events:

# Get accumulated state
curl "https://api.feeds.onhelix.ai/research/tasks/550e8400-e29b-41d4-a716-446655440000/snapshot" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Resume stream from snapshot's sequence
curl -N "https://api.feeds.onhelix.ai/research/tasks/550e8400-e29b-41d4-a716-446655440000/stream?fromSequence=42" \
  -H "Authorization: Bearer YOUR_API_KEY"

See the Streaming Guide for full examples.

Detailed Streaming Mode

Use detail=detailed to see agent-level events:

curl -N "https://api.feeds.onhelix.ai/research/tasks/550e8400-e29b-41d4-a716-446655440000/stream?detail=detailed" \
  -H "Authorization: Bearer YOUR_API_KEY"

This adds agent, tool, text, and thinking events to the stream. See the Streaming Guide for full event documentation.

Quickstart

Prerequisites​

Step 1: Create a Research Task​

Step 2: Stream Results in Real-Time​

Step 3: Retrieve the Completed Result​

Understanding the Results​

Next Steps​

Common Patterns​

Polling Fallback​

JavaScript with EventSource​

Reconnecting with Snapshots​

Detailed Streaming Mode​