Skip to navigation

Unified Speaker Timeline

View as Markdown

GET /api/v1/bots/{bot_id}/get_speaker_timeline returns who spoke and when in a meeting. The timeline is available after the bot leaves the meeting. Until then, the endpoint returns 404 with Manifest file not found. It may still be processing.

curl "https://api.meetstream.ai/api/v1/bots/<BOT_ID>/get_speaker_timeline" \
-H "Authorization: Token <YOUR_API_KEY>"

By default, each platform returns its own timeline format (Google Meet chunks, Zoom sessions, Microsoft Teams slices), as described in the API reference for this endpoint. To get the same format for every platform, add format=unified.

One format for every platform (format=unified)

curl "https://api.meetstream.ai/api/v1/bots/<BOT_ID>/get_speaker_timeline?format=unified" \
-H "Authorization: Token <YOUR_API_KEY>"

With format=unified, Google Meet, Microsoft Teams and Zoom bots all return the same shape, so you need only one parser. Without format, responses are unchanged, so existing integrations keep working.

  • The value is not case-sensitive: unified and UNIFIED both work.
  • An empty value (format=) gives the default response.
  • Any other value returns 400 with Unsupported format. Supported values: unified.

Example response

{
"format": "unified",
"platform": "teams",
"lastUpdated": "2026-01-15T10:42:51.037293+00:00",
"chunks": [
{
"chunkIndex": 6,
"timestamp": "30037333",
"sampleRate": 48000,
"speakerId": "8:orgid:00000000-0000-0000-0000-000000000000",
"speakerName": "Ada Lovelace",
"startByte": 2883584,
"endByte": 2946816,
"endTimestamp": "30696000",
"startTime": "2026-01-15T10:09:38.535312+00:00",
"endTime": "2026-01-15T10:09:39.194098+00:00",
"speakerConfidence": 0.7
}
]
}

Top-level fields

FieldTypeDescription
formatstringAlways unified.
platformstringgmeet, teams or zoom.
lastUpdatedstring or nullWhen the timeline was last written (ISO 8601).
chunksarraySpeaker chunks, in time order.

Chunk fields

Every chunk always has every field below. A value a platform can’t provide is null; no field is ever left out.

FieldTypeDescription
chunkIndexintegerIndex of the chunk as reported by the platform. On Microsoft Teams several consecutive chunks can share the same value, so use the order of the chunks array, not chunkIndex, as the sequence.
timestampstring or nullStart of the chunk, in microseconds from the start of the recording’s audio. A string, as in the Google Meet format.
endTimestampstring or nullEnd of the chunk, in microseconds from the start of the recording’s audio.
sampleRateintegerSample rate of the meeting’s mixed audio, in Hz.
speakerIdstring or nullThe platform’s ID for the speaker. null when there is none, for example when no one is speaking.
speakerNamestringThe speaker’s display name, or NoSpeaker when no one is speaking.
startByte / endByteinteger or nullPosition of the chunk in the meeting’s mixed audio as raw 16-bit mono PCM at sampleRate (2 bytes per sample).
startTime / endTimestring or nullWall-clock start and end (ISO 8601, UTC).
speakerConfidencenumber or nullHow confident the speaker attribution is, from 0 to 1.

To get seconds from the start of the audio, divide timestamp (or endTimestamp) by 1,000,000.

Platform differences

Google MeetMicrosoft TeamsZoom
CoverageThe whole recording, in short chunks. NoSpeaker until the first person speaksThe whole recording, in short chunks, including NoSpeaker for silenceSpeaking turns only; gaps between chunks are silence
startTime / endTimenullProvidedProvided
speakerConfidencenullProvidednull
speakerIdProvidedProvided; null for NoSpeakerProvided (the Zoom user ID, as a string)

For some older Zoom recordings the start of the audio is not known. Then timestamp, endTimestamp, startByte and endByte are null, and startTime / endTime still give the wall-clock times.

Parsing example

The same code works for every platform:

import requests
resp = requests.get(
f"https://api.meetstream.ai/api/v1/bots/{bot_id}/get_speaker_timeline",
params={"format": "unified"},
headers={"Authorization": f"Token {api_key}"},
)
resp.raise_for_status()
body = resp.json()
if "speaker_timeline_url" in body: # large timeline, see below
body = requests.get(body["speaker_timeline_url"]).json()
for chunk in body["chunks"]:
if chunk["speakerName"] == "NoSpeaker" or chunk["timestamp"] is None:
continue
start_s = int(chunk["timestamp"]) / 1_000_000
end_s = int(chunk["endTimestamp"]) / 1_000_000
print(f"{start_s:8.2f}s - {end_s:8.2f}s {chunk['speakerName']}")

Current limitation

For bots whose meeting data is stored in a data-residency region outside the US, format=unified returns 409 for now. Call without format to get their timeline in the platform’s own format.

Large timelines

Most timelines are returned inline: the response body is the timeline JSON itself.

Long or busy meetings can produce timelines too large to return in one API response (about 5 MB or more). For those, the endpoint still returns 200 OK, but the body is a small object with a download link instead of the timeline:

{
"bot_id": "abc-123",
"speaker_timeline_url": "https://...",
"size_bytes": 8421337,
"truncated": false
}
FieldTypeDescription
bot_idstringThe bot the timeline belongs to.
speaker_timeline_urlstringPre-signed URL to download the full timeline JSON. Valid for 1 hour; call the endpoint again for a fresh link.
size_bytesintegerSize of the timeline file in bytes.
truncatedbooleanAlways false: the file at the URL is the complete timeline, in the same format an inline response would have. With format=unified, the file is in the unified format.

The unified format can be smaller or larger than a platform’s own format, so the same meeting may come back inline in one format and as a download link in the other. Always check for speaker_timeline_url.

Handling both shapes

Check for speaker_timeline_url and download the timeline when it is present:

import requests
resp = requests.get(
f"https://api.meetstream.ai/api/v1/bots/{bot_id}/get_speaker_timeline",
headers={"Authorization": f"Token {api_key}"},
)
resp.raise_for_status()
body = resp.json()
if isinstance(body, dict) and "speaker_timeline_url" in body:
timeline = requests.get(body["speaker_timeline_url"]).json()
else:
timeline = body

The download link does not need your API key. Treat it like the meeting data itself and do not share it.

Errors

StatusWhen
400Unsupported format value, or missing bot ID.
403The bot belongs to another account.
404Bot not found, or the timeline is not ready yet (the bot is still in the meeting or processing).
409format=unified for a bot whose data is stored in a region outside the US.