Get Report

Retrieves a report by its ID.

Endpoint

GET /api/reports/:id

Path Parameters

Parameter	Type	Description
id	string	The report ID (e.g., rpt_xyz789) or case ID

Request Example

curl https://api.silentwitness.ai/api/reports/rpt_xyz789 \
  -H "X-API-Key: sk-your-api-key"

Response

Success - Processing (200 OK)

{
  "success": true,
  "data": {
    "id": "rpt_xyz789",
    "case_id": "case_abc123",
    "type": "technical_report",
    "status": "processing",
    "progress": {
      "current_step": "biomechanics_analysis",
      "steps_completed": ["delta_v_calculation"],
      "message": "Running biomechanics analysis..."
    },
    "output": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z"
  }
}

Success - Completed (200 OK)

{
  "success": true,
  "data": {
    "id": "rpt_xyz789",
    "case_id": "case_abc123",
    "type": "technical_report",
    "status": "completed",
    "progress": {
      "current_step": "report_generation",
      "steps_completed": ["delta_v_calculation", "biomechanics_analysis", "report_generation"],
      "message": "Report generation complete"
    },
    "output": {
      "pdf_url": "https://storage.silentwitness.ai/reports/rpt_xyz789.pdf",
      "docx_url": "https://storage.silentwitness.ai/reports/rpt_xyz789.docx"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:45:00Z"
  }
}

Success - Not Found (200 OK)

Returns null data if the report doesn't exist (Stripe-style behavior):

{
  "success": true,
  "data": null
}

Status Values

Status	Description
pending	Report creation accepted, processing not started
processing	Report is being generated
completed	Report is ready for download
failed	Report generation failed
cancelled	Report was cancelled

Progress Object

The progress field provides information about the current state:

Field	Description
current_step	The step currently being processed
steps_completed	Array of completed step names
message	Human-readable status message

Output Object

When status is completed, the output object contains download URLs:

Field	Description
pdf_url	Signed URL to download PDF version (expires in 1 hour)
docx_url	Signed URL to download DOCX version (expires in 1 hour)

Polling Strategy

For report generation, we recommend:

1. Poll every 5 seconds
2. Set a maximum timeout of 10-15 minutes
3. Stop polling when status is completed, failed, or cancelled

async function waitForReport(reportId) {
  const maxAttempts = 180; // 15 minutes at 5-second intervals

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`/api/reports/${reportId}`);
    const { data } = await response.json();

    if (!data) {
      throw new Error('Report not found');
    }

    if (data.status === 'completed') {
      return data;
    }

    if (data.status === 'failed' || data.status === 'cancelled') {
      throw new Error(`Report ${data.status}: ${data.progress?.message}`);
    }

    await new Promise(resolve => setTimeout(resolve, 5000));
  }

  throw new Error('Report generation timeout');
}