History SSE

Connection Info

Note: The browser's native EventSource API does not support custom headers. Use the fetch API with ReadableStream, or use an SSE client library that supports headers.

Endpoint Overview

GET /api/v1/sse/history/transcribe/{taskId}

Description

Loads the complete conversation record for a specified task, including all sentences and the summary. The data is sent one item at a time over an SSE stream.

Difference from the Transcript Download API (GET /api/v1/tasks/{taskId}/transcript/export):

• This endpoint: for progressive loading; pushes raw structured data (JSON fragments) sentence by sentence as an event stream, so the front end can render the UI progressively.
• Transcript download: for offline download; returns the complete file (TXT / SRT / SBV / VTT / CSV) in one response, ready to open in subtitle software or a spreadsheet.

Use Cases

• View the recording details page
• Load historical transcripts

Authentication

Header: X-API-Key (see Authentication)

Request Parameters

Request Example

curl -N "https://vas-poc.vurbo.ai/api/v1/sse/history/transcribe/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

// Use the fetch API (because EventSource does not support headers)
async function connectSSE(taskId, apiKey) {
  const response = await fetch(
    `https://vas-poc.vurbo.ai/api/v1/sse/history/transcribe/${taskId}`,
    {
      headers: {
        'X-API-Key': apiKey
      }
    }
  );
  const reader = response.body.getReader();
  // ... handle SSE events
}

Event Sequence

1. connected        → connection confirmation
2. init_metadata    → send task metadata
3. init_sentence    → send sentences one by one (repeats N times)
4. init_summary     → send summary
5. init_done        → initialization complete

Event Formats

connected

{
  "message": "History service connected (taskId: xxx)"
}

init_metadata

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Meeting Notes",
  "created_at": "2026-02-23T10:00:00Z",
  "type": "transcribe",
  "has_speaker_diarization": true,
  "transcription_languages": ["zh-TW"],
  "translation_languages": ["en-US"],
  "summary_template": "general",
  "summary_language": "zh-TW",
  "speaker_aliases": {"speaker_1": "Manager Wang"}
}

init_sentence

{
  "sid": 1,
  "origin": "Hello",
  "translations": {
    "en-US": "Hello"
  },
  "start_time": "00:05",
  "speaker_id": "speaker_1",
  "speaker_label": "Manager Wang"
}

If a sentence has a translation failure, it carries an additional translation_errors field (present only when there is a failure). This lets the front end distinguish "the language was never scheduled for translation" (translations missing the key) from "it was translated but failed" (translation_errors has the key). The same language may have both an older translation and a failure record (a failed retranslation keeps the previous translation), so read both fields together:

{
  "sid": 5,
  "origin": "Sentence with sensitive words",
  "translations": {
    "en-US": "Sensitive sentence"
  },
  "translation_errors": {
    "ja-JP": "llm_content_filtered"
  },
  "start_time": "00:25",
  "speaker_id": "speaker_1",
  "speaker_label": "Manager Wang"
}

If the user has edited the original text of a sentence (via PATCH /api/v1/tasks/{id}/entries/{sid}), it carries additional original_text_raw and original_text_edited_at fields (present only after editing):

{
  "sid": 7,
  "origin": "Corrected text",
  "original_text_raw": "Original STT output",
  "original_text_edited_at": "2026-05-06T10:30:00.000000Z",
  "translations": { "en-US": "Corrected text" },
  "start_time": "00:35",
  "speaker_id": "speaker_1",
  "speaker_label": "Manager Wang"
}

For multi-channel recordings (recognition_mode: "multi_channel"), each sentence carries an additional channel_id field (present only for multi-channel recordings; single-channel recordings do not carry this field):

{
  "sid": 9,
  "origin": "Good morning, everyone",
  "translations": {
    "en-US": "Good morning, everyone"
  },
  "start_time": "00:40",
  "speaker_id": "channel_1",
  "speaker_label": "Manager Wang",
  "channel_id": 1
}

Front-end detection: Determine whether a sentence has been edited by the presence of the field ('original_text_raw' in data or data.original_text_raw !== undefined). Do not compare origin === original_text_raw — the user may have edited the text and then changed it back to the same string; in that case the text is equal but the "edited" marker should still be shown.

v1.5.3 naming reversal: speaker_id is reversed from the display name to the original ID; a new speaker_label field holds the display label. Speaker edits (reassign / merge) always use speaker_id as the locating key. See the V1.5.3 changelog.

Multi-channel recordings (V1.10.0): speaker_id uses the channel_{N} format (N = channel number); speaker identity is determined by the physical channel rather than inferred by AI. speaker_label is the speaker_name configured for that channel (or the display name after a rename_speaker change); it is equal to speaker_id when there is no alias. The informational overlap between channel_id and speaker_id is deliberate — channel_id is an immutable record of the source channel, so each can be traced separately for auditing. Also note that for multi-channel recordings, sentences are sent sorted by time and sid is not guaranteed to be increasing; clients must not use sid values to infer ordering.

init_summary

In addition to the summary text text, this includes mode-aware metadata (mode / template / plain_text / prompt_snapshot), which lets the client trace the mode, effective slug, and customer prompt content (custom mode) that correspond to that summary.

v1.5.5 adds fallback_level / dropped_segments: these appear only when the summary actually went through the LLM service content-filter automatic fallback (neutral mode or segment-omission mode), for auditing and UI hints during history playback.

Example (standard mode succeeds directly, no fallback):

{
  "text": "Summary content...",
  "mode": "custom",
  "template": "acme-meeting-v2",
  "plain_text": true,
  "summary_language": "zh-TW",
  "prompt_snapshot": "Please emphasize KPIs"
}

Example (segment-omission mode triggered, generated after 2 transcript segments were omitted):

{
  "text": "Summary content (2 segments omitted)...",
  "mode": "custom",
  "template": "acme-meeting-v2",
  "plain_text": true,
  "summary_language": "zh-TW",
  "prompt_snapshot": "Please emphasize KPIs",
  "fallback_level": 3,
  "dropped_segments": [3, 7]
}

summary_language and the field of the same name in init_metadata: to determine the language of the summary itself, use the summary_language of this event. When there is no summary, init_metadata.summary_language may still carry the language setting from the recording while this field is null; the two differing is expected.

fallback_level / dropped_segments and prompt_snapshot are complementary: the former records the actual execution path (whether a fallback was taken), and the latter records the customer intent (the original prompt content). Even if a fallback was triggered and the customer prompt was not actually used, prompt_snapshot still preserves the original text as an audit record. See V1.5.5 changelog – LLM service content-filter automatic fallback.

init_done

{
  "totalSentences": 10
}

Edge Case: No Speech Content (V1.3.7)

If the task is silent throughout, the volume is too low, there is too much noise, or the recognition language does not match the actual audio—so that the speech recognition engine recognizes no sentences—this endpoint still completes with the normal event sequence (not an sse_transcript_not_found error):

• init_metadata is sent normally
• init_sentence is sent 0 times (no sentences)
• The text of init_summary is an empty string "", and its summary_language is null
• The totalSentences of init_done is 0

This behavior applies to both sources: real-time recording (WebSocket recording ends) and file import (offline processing completes), and is aligned with the "zero recognition results" legalization behavior of the V1.3.5 import flow. The client should use totalSentences === 0 to decide whether to show a "no speech content" empty state, rather than treating it as an error branch. See File Import Guide – Behavior When Audio Cannot Be Recognized.

Specific Error Codes

Front-End Example

async function loadHistory(taskId, apiKey) {
  const response = await fetch(
    `https://vas-poc.vurbo.ai/api/v1/sse/history/transcribe/${taskId}`,
    {
      headers: {
        'X-API-Key': apiKey
      }
    }
  );

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const text = decoder.decode(value);
    // Parse the SSE format: event: xxx\ndata: {...}\n\n
    const events = parseSSE(text);

    for (const event of events) {
      if (event.type === 'init_metadata') {
        console.log('Task info:', event.data.title);
      } else if (event.type === 'init_sentence') {
        console.log(`[${event.data.start_time}] ${event.data.origin}`);
        if (event.data.translations) {
          console.log(`Translations:`, event.data.translations);
        }
      } else if (event.type === 'init_summary') {
        console.log('Summary:', event.data.text);
      } else if (event.type === 'init_done') {
        console.log(`Load complete, ${event.data.totalSentences} sentences total`);
      }
    }
  }
}

Version: V1.24.1 Last Updated: 2026-10-01