Skip to main content
Skip to main content
Helix
Book a briefing →

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",
    "source_types": [{ "type": "web" }],
    "supervisor_thinking": [],
    "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: supervisor_thinking
data: {"content":"I'll decompose this topic into three areas: materials science, EV integration, and manufacturing challenges."}
id: 1

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

event: source
data: {"url":"https://example.com/solid-state-research","title":"Solid-State Battery Breakthroughs","score":0.85,"topic":"solid-state-battery-materials","source_type":{"type":"web"}}
id: 5

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

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

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"}
id: 42

event: done
data: {}
id: 43

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",
    "source_types": [{ "type": "web" }],
    "supervisor_thinking": [
      {
        "content": "I'll decompose this topic into three areas: materials science, EV integration, and manufacturing challenges.",
        "timestamp": 1705312200000
      }
    ],
    "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",
          "score": 0.92,
          "topic": "solid-state-battery-materials",
          "source_type": { "type": "web" }
        }
      ],
      "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 cited in the report, each with a relevance score, topic, and source_type
  • sub_reports_count — Number of sub-reports that were synthesized
  • confidence_level — Overall confidence in the research quality (high, medium, low)

Task-level fields:

  • source_types — The source types used for this research task (e.g., [{ "type": "web" }])
  • supervisor_thinking — The supervisor agent's reasoning as it planned and coordinated the research, with timestamps

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, supervisor thinking, 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('supervisor_thinking', (e) => {
  const data = JSON.parse(e.data);
  console.log(`Supervisor: ${data.content}`);
});

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.