Research API

GET /api/research//stream

Stream research results in real-time using Server-Sent Events (SSE). This endpoint spawns research agents and streams their findings as they arrive.

Authentication

No authentication required (for hackathon demo).

Path Parameters

person_name

string

required

Person’s full name to research.

Query Parameters

image_url

string

Optional photo URL to associate with the person record.

Response

Server-Sent Events stream with the following event types:

Event: `init`

Sent immediately upon connection.

person_id

string

Created person record ID (or null if Convex unavailable).

person_name

string

Echo of the person name being researched.

image_url

string

Echo of the provided image URL.

live_session_id

string

Browser Use session ID for live view (initially null, updated in background).

live_url

string

Browser Use live session URL (initially null, updated in background).

Event: `result`

Sent for each research agent that completes.

agent_name

string

Name of the research agent (e.g., “exa_fast_pass”, “linkedin_agent”).

snippets

array

Array of text snippets extracted by the agent.

urls_found

array

Array of relevant URLs discovered.

confidence

number

Agent’s confidence in the results (0.0 to 1.0).

duration_ms

integer

Time taken by the agent in milliseconds.

Event: `dossier`

Sent once after synthesis completes.

summary

string

Executive summary.

title

string

Current job title.

company

string

Current employer.

work_history

array

Work experience array.

education

array

Education background.

Social media links.

notable_activity

array

Notable achievements.

conversation_hooks

array

Event: `complete`

Sent when all agents finish and synthesis completes.

person_id

string

Final person record ID.

total_sources

integer

Number of research agents that completed.

total_urls

integer

Total URLs discovered across all agents.

Example Request (JavaScript)

const streamResearch = (personName, imageUrl = null) => {
  const url = new URL('https://api.jarvis.local/api/research/' + encodeURIComponent(personName) + '/stream');
  if (imageUrl) url.searchParams.set('image_url', imageUrl);
  
  const eventSource = new EventSource(url);
  
  eventSource.addEventListener('init', (e) => {
    const data = JSON.parse(e.data);
    console.log('Research started:', data.person_id);
  });
  
  eventSource.addEventListener('result', (e) => {
    const result = JSON.parse(e.data);
    console.log(`[${result.agent_name}] Found ${result.snippets.length} snippets`);
  });
  
  eventSource.addEventListener('dossier', (e) => {
    const dossier = JSON.parse(e.data);
    console.log('Dossier generated:', dossier.summary);
  });
  
  eventSource.addEventListener('complete', (e) => {
    const final = JSON.parse(e.data);
    console.log(`Research complete: ${final.total_sources} sources, ${final.total_urls} URLs`);
    eventSource.close();
  });
  
  eventSource.onerror = (err) => {
    console.error('SSE error:', err);
    eventSource.close();
  };
  
  return eventSource;
};

// Usage
const es = streamResearch('Elon Musk', 'https://example.com/elon.jpg');

Example Request (curl)

curl -N https://api.jarvis.local/api/research/Elon%20Musk/stream

Example Response Stream

event: init
data: {"person_id":"person_xyz123","person_name":"Elon Musk","image_url":null,"live_session_id":null,"live_url":null}

event: result
data: {"agent_name":"exa_fast_pass","snippets":["CEO of Tesla and SpaceX","Founded The Boring Company"],"urls_found":["https://tesla.com","https://spacex.com"],"confidence":0.95,"duration_ms":1243}

event: result
data: {"agent_name":"linkedin_agent","snippets":["500+ connections","Former CEO of PayPal"],"urls_found":["https://linkedin.com/in/elonmusk"],"confidence":0.88,"duration_ms":5621}

event: dossier
data: {"summary":"Elon Musk is a technology entrepreneur...","title":"CEO","company":"Tesla, SpaceX","work_history":[...],"social_profiles":{...},"notable_activity":[...],"conversation_hooks":[...],"risk_flags":[]}

event: complete
data: {"person_id":"person_xyz123","total_sources":4,"total_urls":12}

Status Codes

200 - Stream established (keep connection open to receive events)
503 - Browser Use API key not configured
500 - Server error during research initialization

Research Agents

The following agents run in parallel:

exa_fast_pass - Exa API for quick background search (2-5s)
linkedin_agent - Browser Use agent scraping LinkedIn (10-30s)
twitter_agent - Browser Use agent scraping Twitter/X (10-30s)
google_agent - Browser Use agent scraping Google results (5-15s)
crunchbase_agent - Browser Use agent for corporate data (15-45s)

Performance

First result: 2-5 seconds (Exa fast-pass)
Most results: 10-30 seconds
Full completion: 30-60 seconds
Synthesis: Additional 5-10 seconds

Best Practices

Keep connection open until complete event

Handle reconnection with exponential backoff

Display partial results as they arrive for better UX

Connections may timeout after 5 minutes of inactivity

Browser Use sessions are rate-limited (max 10 concurrent)

POST /api/agents/research

Start research agents for a person (returns immediately without waiting).

Request

person_id

string

required

Existing person record ID.

person_name

string

required

Person’s full name.

sources

array

default:["linkedin","twitter","google"]

Array of source types to research. Available sources:

linkedin - LinkedIn profile and activity
twitter - Twitter/X profile and tweets
google - Google search results
crunchbase - Crunchbase company/person data

Response

person_id

string

Echo of the person ID.

agents

array

Array of spawned agent sessions.

Show Agent info

source_tp

string

Source type (e.g., “SOCIAL”, “MEDIA”, “CORPORATE”).

source_nm

string

Human-readable source name (e.g., “LinkedIn Profile”).

session_id

string

Browser Use session ID.

task_id

string

Browser Use task ID.

live_url

string

URL to watch the agent live.

session_status

string

Initial status (always “running”).

Example Request

curl -X POST https://api.jarvis.local/api/agents/research \
  -H "Content-Type: application/json" \
  -d '{
    "person_id": "person_abc123",
    "person_name": "Jane Doe",
    "sources": ["linkedin", "twitter", "crunchbase"]
  }'

Example Response

{
  "person_id": "person_abc123",
  "agents": [
    {
      "source_tp": "SOCIAL",
      "source_nm": "LinkedIn Profile",
      "session_id": "ses_linkedin_xyz",
      "task_id": "task_linkedin_123",
      "live_url": "https://cloud.browser-use.com/sessions/ses_linkedin_xyz/live",
      "session_status": "running"
    },
    {
      "source_tp": "SOCIAL",
      "source_nm": "Twitter/X Activity",
      "session_id": "ses_twitter_abc",
      "task_id": "task_twitter_456",
      "live_url": "https://cloud.browser-use.com/sessions/ses_twitter_abc/live",
      "session_status": "running"
    }
  ]
}

Status Codes

200 - Agents started successfully
400 - Invalid request (missing fields or unknown sources)
503 - Browser Use API not configured
500 - Server error starting agents

GET /api/agents/sessions/

Get status and results for a research agent session.

Path Parameters

session_id

string

required

Browser Use session ID from /api/agents/research response.

Response

session_id

string

Echo of the session ID.

session_status

string

Current status: pending, running, completed, or failed.

live_url

string

URL to watch the agent live (only available while running).

URL to replay the session (only available after completion).

task

object

Task execution details.

Show Task info

task_id

string

Task ID

status

string

Task status

steps

array

Array of task steps.

Show Step info

number

integer

Step number

url

string

Current page URL

screenshot_url

string

Screenshot of the step

next_goal

string

Agent’s next goal

output

string

Final task output

Example Request

curl -X GET https://api.jarvis.local/api/agents/sessions/ses_linkedin_xyz

Example Response

{
  "session_id": "ses_linkedin_xyz",
  "session_status": "completed",
  "live_url": null,
  "share_url": "https://cloud.browser-use.com/share/ses_linkedin_xyz",
  "task": {
    "task_id": "task_linkedin_123",
    "status": "finished",
    "steps": [
      {
        "number": 1,
        "url": "https://linkedin.com",
        "screenshot_url": "https://storage.browser-use.com/screenshots/step1.png",
        "next_goal": "Search for Jane Doe"
      },
      {
        "number": 2,
        "url": "https://linkedin.com/in/janedoe",
        "screenshot_url": "https://storage.browser-use.com/screenshots/step2.png",
        "next_goal": "Extract profile details"
      }
    ],
    "output": "Current role: Senior Software Engineer at TechCorp. Education: MIT CS. 500+ connections."
  }
}

Status Codes

200 - Session status retrieved
404 - Session not found
500 - Server error retrieving session

Endpoints

Convex Functions

GET /api/research//stream

Authentication

Path Parameters

Query Parameters

Response

Event: `init`

Event: `result`

Event: `dossier`

Event: `complete`

Example Request (JavaScript)

Example Request (curl)

Example Response Stream

Status Codes

Research Agents

Performance

Best Practices

POST /api/agents/research

Request

Response

Example Request

Example Response

Status Codes

GET /api/agents/sessions/

Path Parameters

Response

Example Request

Example Response

Status Codes

Build docs developers (and LLMs) love

Endpoints

Convex Functions

​GET /api/research//stream

​Authentication

​Path Parameters

​Query Parameters

​Response

​Event: init

​Event: result

​Event: dossier

​Event: complete

​Example Request (JavaScript)

​Example Request (curl)

​Example Response Stream

​Status Codes

​Research Agents

​Performance

​Best Practices

​POST /api/agents/research

​Request

​Response

​Example Request

​Example Response

​Status Codes

​GET /api/agents/sessions/

​Path Parameters

​Response

​Example Request

​Example Response

​Status Codes

Build docs developers (and LLMs) love

GET /api/research//stream

Authentication

Path Parameters

Query Parameters

Response

Event: `init`

Event: `result`

Event: `dossier`

Event: `complete`

Example Request (JavaScript)

Example Request (curl)

Example Response Stream

Status Codes

Research Agents

Performance

Best Practices

POST /api/agents/research

Request

Response

Example Request

Example Response

Status Codes

GET /api/agents/sessions/

Path Parameters

Response

Example Request

Example Response

Status Codes