Skip to main content
GET
Stream case progress updates (SSE)
Establish a Server-Sent Events (SSE) connection to receive real-time progress updates during case analysis. This endpoint provides live streaming of analysis events including file processing stages, progress percentages, and completion notifications.
Network Restrictions: SSE streams may not be available on corporate or restricted networks due to proxy configurations, firewall rules, or man-in-the-middle (MITM) detection systems. If streaming fails, use the polling endpoint as a fallback.

Permission

You can follow a case you created, or any case in your organisation if you have organisation_cases:read; otherwise the API returns 404. Per-file events cover only the files you uploaded, and those uploaded through document requests into a case you created, unless you have organisation_files:read. Shared cases, if enabled for your organisation, also give you reach to every case and file. See Permissions and API Keys.

Event Types

The stream provides several event types to help you track progress:
  • file.analysis.progress: Real-time updates on individual file processing stages.
  • file.analysis.completed: Notification that a specific file has finished analysis.
  • case.analysis.completed: Final event indicating the entire case is complete.
  • heartbeat: Connection keep-alive signal.
  • stream_closed: Indicates the stream has ended (e.g., if analysis was already finished).

Best Practices

  1. Reconnection Logic: Implement automatic reconnection with exponential backoff to handle transient network issues.
  2. Fallback Mechanism: Always detect SSE connection failures and automatically switch to polling.
  3. Resource Cleanup: Ensure connections are closed when the user leaves the progress screen or the analysis completes.

Authorizations

x-api-key
string
header
required

Path Parameters

id
string
required

Case ID

Query Parameters

api_key
string

API key for authentication (alternative to access_token)

access_token
string

Access token for JWT authentication

Response

Unauthorized (invalid or missing authentication token)

error_code
string
required

Machine-readable error code for programmatic handling

Examples:

"request.cases.file.missing-risk-score"

"request.authentication.invalid-token"

"request.forbidden"

"request.cases.case.not-found"

"request.cases.case.already-locked"

error_message
string
required

Human-readable error message explaining what went wrong

Example:

"User tried to perform an invalid operation on a file without a risk score."

error_details
object
Example: