Status API

Check the progress and results of deep research investigations

GET /api/deep-research/status/:messageId

Status API

cURL

curl --request GET \
  --url https://api.example.com/api/deep-research/status/:messageId \
  --header 'Authorization: <authorization>'

200

{
  "400": {},
  "401": {},
  "403": {},
  "404": {},
  "409": {},
  "500": {},
  "status": "<string>",
  "messageId": "<string>",
  "conversationId": "<string>",
  "progress": {
    "currentStep": "<string>",
    "completedSteps": [
      "<string>"
    ]
  },
  "result": {
    "text": "<string>",
    "files": [
      {
        "filename": "<string>",
        "mimeType": "<string>",
        "size": 123
      }
    ],
    "papers": [
      {
        "title": "<string>",
        "authors": [
          "<string>"
        ],
        "doi": "<string>",
        "year": 123,
        "abstract": "<string>"
      }
    ],
    "webSearchResults": [
      {}
    ]
  },
  "error": "<string>",
  "ok": true,
  "jobId": "<string>",
  "message": "<string>",
  "previousAttempts": 123
}

Overview

The Status API allows you to check the progress of deep research jobs, retrieve completed results, and monitor active research cycles.

Authentication

Authentication is required and enforces ownership validation.

Authorization · string · required

Bearer token for JWT authentication

X-API-Key · string

Alternative API key authentication

---

GET /api/deep-research/status/:messageId

Retrieve the current status of a deep research investigation.

Path Parameters

messageId · string · required

The message ID returned from POST /api/deep-research/start

Security

• User can only access their own research jobs
• userId extracted from authenticated context (never from query params)
• Returns 403 Forbidden if accessing another user’s job

Response: Processing

Returned when research is still running.

status · string

Current status: processing

messageId · string

The message ID being tracked

conversationId · string

Associated conversation ID

progress · object

Progress information

Show progress properties

currentStep · string

Name of currently executing step (e.g., “literature_search”, “hypothesis_generation”)

completedSteps · string[]

Array of completed step names

Response: Completed

Returned when research has finished successfully.

status · string

Status: completed

messageId · string

The message ID

conversationId · string

Conversation ID

result · object

Research results

Show result properties

text · string

Final research summary with hypothesis, insights, and discoveries

files · array

Array of generated files (plots, figures, datasets)

Show file properties

filename · string

File name

mimeType · string

MIME type (e.g., “image/png”, “text/csv”)

size · number

File size in bytes

papers · array

Array of relevant papers from literature search

Show paper properties

title · string

Paper title

authors · string[]

Author names

doi · string

DOI identifier

year · number

Publication year

abstract · string

Paper abstract

webSearchResults · array

Web search results if web search was performed

Response: Failed

Returned when research encountered an error.

status · string

Status: failed

messageId · string

The message ID

conversationId · string

Conversation ID

error · string

Error message describing what went wrong

---

Examples

Example: Check Status (Processing)

curl https://api.bioagents.xyz/api/deep-research/status/msg_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "status": "processing",
  "messageId": "msg_abc123",
  "conversationId": "conv_xyz789",
  "progress": {
    "currentStep": "analysis_execution",
    "completedSteps": [
      "planning",
      "literature_search",
      "hypothesis_generation"
    ]
  }
}

Example: Check Status (Completed)

curl https://api.bioagents.xyz/api/deep-research/status/msg_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "status": "completed",
  "messageId": "msg_abc123",
  "conversationId": "conv_xyz789",
  "result": {
    "text": "## Research Summary\n\nCaloric restriction extends lifespan through multiple conserved pathways...\n\n## Hypothesis\n\nCaloric restriction activates AMPK and inhibits mTOR, leading to increased autophagy and improved proteostasis, which extends cellular lifespan...\n\n## Key Insights\n\n1. mTOR inhibition is both necessary and sufficient for CR-mediated longevity\n2. AMPK activation precedes autophagy induction by 2-4 hours\n3. Sirtuins require NAD+ availability for lifespan extension\n\n## Discoveries\n\n**Novel Finding 1**: TFEB nuclear translocation correlates with lifespan extension (r=0.89, p<0.001)\n- Evidence: Analysis task ana-2 (job_xyz123)\n- Supporting literature: doi:10.1016/j.celrep.2016.12.063\n\n**Novel Finding 2**: CR upregulates Atg7 expression 1.52-fold before detectable autophagy flux changes\n- Evidence: Analysis task ana-2 (job_xyz123)\n- Supporting literature: doi:10.1038/nature24630",
    "files": [
      {
        "filename": "gene_expression_heatmap.png",
        "mimeType": "image/png",
        "size": 245678
      },
      {
        "filename": "lifespan_correlation.png",
        "mimeType": "image/png",
        "size": 189234
      }
    ],
    "papers": [
      {
        "title": "mTOR inhibition extends lifespan through conserved pathways",
        "authors": ["Smith J", "Johnson A"],
        "doi": "10.1126/science.1215135",
        "year": 2012,
        "abstract": "We demonstrate that pharmacological inhibition of mTOR..."
      },
      {
        "title": "Autophagy gene 7 upregulation promotes longevity",
        "authors": ["Lee K", "Park S"],
        "doi": "10.1038/nature24630",
        "year": 2017,
        "abstract": "Genetic upregulation of Atg7 extends lifespan in multiple species..."
      }
    ]
  }
}

Example: Check Status (Failed)

curl https://api.bioagents.xyz/api/deep-research/status/msg_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "status": "failed",
  "messageId": "msg_abc123",
  "conversationId": "conv_xyz789",
  "error": "Literature search service unavailable"
}

---

POST /api/deep-research/retry/:jobId

Manually retry a failed deep research job (only available in queue mode).

Authentication

Must be the owner of the job being retried.

Path Parameters

jobId · string · required

The job ID to retry

Response

ok · boolean

Whether retry was successful

jobId · string

The job ID being retried

status · string

New status: retrying

message · string

Human-readable status message

previousAttempts · number

Number of previous retry attempts

Example: Retry Failed Job

curl -X POST https://api.bioagents.xyz/api/deep-research/retry/msg_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "ok": true,
  "jobId": "msg_abc123",
  "status": "retrying",
  "message": "Job has been queued for retry",
  "previousAttempts": 1
}

---

Error Codes

400 · Bad Request

• Missing required parameter: messageId
• Cannot retry job in current state (must be failed)

401 · Unauthorized

Missing or invalid authentication credentials

403 · Forbidden

Attempting to access another user’s research job

404 · Not Found

• Message not found
• Job not found
• Queue mode not enabled (for retry endpoint)

409 · Conflict

Deep research already running for this conversation (retry blocked)

500 · Internal Server Error

• Message has no associated state
• State not found
• Failed to check status
• Job missing conversation run metadata

---

Polling Best Practices

Recommended Polling Strategy

async function pollResearchStatus(messageId, authToken) {
  const maxAttempts = 300; // 5 minutes with 1-second intervals
  let attempts = 0;
  
  while (attempts < maxAttempts) {
    const response = await fetch(
      `https://api.bioagents.xyz/api/deep-research/status/${messageId}`,
      {
        headers: {
          'Authorization': `Bearer ${authToken}`
        }
      }
    );
    
    const data = await response.json();
    
    if (data.status === 'completed') {
      return data.result;
    }
    
    if (data.status === 'failed') {
      throw new Error(data.error);
    }
    
    // Still processing, wait before next poll
    await new Promise(resolve => setTimeout(resolve, 1000));
    attempts++;
  }
  
  throw new Error('Research timed out');
}

WebSocket Alternative

For real-time updates, connect to WebSocket endpoint:

const ws = new WebSocket(`wss://api.bioagents.xyz/ws?userId=${userId}`);

ws.onmessage = (event) => {
  const update = JSON.parse(event.data);
  
  if (update.type === 'state_updated') {
    console.log('Research state updated:', update.conversationStateId);
  }
  
  if (update.type === 'message_updated') {
    console.log('Message content updated:', update.messageId);
  }
};

---

State Tracking

The status endpoint reads from the message’s associated state record:

• state.values.status: Overall status flag
• state.values.steps: Map of step names to execution timestamps
• state.values.finalResponse: Completed research summary
• state.values.error: Error message if failed
• state.values.rawFiles: Generated artifacts
• state.values.*Papers: Papers from various sources

---

Related Endpoints

• Deep Research API - Start new research
• Chat API - Simple queries without iteration
• Health API - Service health check