> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.meetstream.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.meetstream.ai/_mcp/server.

# Unified Speaker Timeline

`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.`

```bash
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`)

```bash
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

```json
{
  "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

| Field | Type | Description |
|---|---|---|
| `format` | `string` | Always `unified`. |
| `platform` | `string` | `gmeet`, `teams` or `zoom`. |
| `lastUpdated` | `string` or `null` | When the timeline was last written (ISO 8601). |
| `chunks` | `array` | Speaker 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.

| Field | Type | Description |
|---|---|---|
| `chunkIndex` | `integer` | Index 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. |
| `timestamp` | `string` or `null` | Start of the chunk, in microseconds from the start of the recording's audio. A string, as in the Google Meet format. |
| `endTimestamp` | `string` or `null` | End of the chunk, in microseconds from the start of the recording's audio. |
| `sampleRate` | `integer` | Sample rate of the meeting's mixed audio, in Hz. |
| `speakerId` | `string` or `null` | The platform's ID for the speaker. `null` when there is none, for example when no one is speaking. |
| `speakerName` | `string` | The speaker's display name, or `NoSpeaker` when no one is speaking. |
| `startByte` / `endByte` | `integer` or `null` | Position of the chunk in the meeting's mixed audio as raw 16-bit mono PCM at `sampleRate` (2 bytes per sample). |
| `startTime` / `endTime` | `string` or `null` | Wall-clock start and end (ISO 8601, UTC). |
| `speakerConfidence` | `number` or `null` | How 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 Meet | Microsoft Teams | Zoom |
|---|---|---|---|
| Coverage | The whole recording, in short chunks. `NoSpeaker` until the first person speaks | The whole recording, in short chunks, including `NoSpeaker` for silence | Speaking turns only; gaps between chunks are silence |
| `startTime` / `endTime` | `null` | Provided | Provided |
| `speakerConfidence` | `null` | Provided | `null` |
| `speakerId` | Provided | Provided; `null` for `NoSpeaker` | Provided (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:

```python
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:

```json
{
  "bot_id": "abc-123",
  "speaker_timeline_url": "https://...",
  "size_bytes": 8421337,
  "truncated": false
}
```

| Field | Type | Description |
|---|---|---|
| `bot_id` | `string` | The bot the timeline belongs to. |
| `speaker_timeline_url` | `string` | Pre-signed URL to download the full timeline JSON. Valid for 1 hour; call the endpoint again for a fresh link. |
| `size_bytes` | `integer` | Size of the timeline file in bytes. |
| `truncated` | `boolean` | Always `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:

```python
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

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