get_live_chat_messages
Retrieve recent live chat messages from a YouTube live stream using pagination. Poll with a page token to get only new messages.
Instructions
Get recent live chat messages from a streaming video.
Fetches live chat messages with pagination support for efficient polling.
Use the returned next_page_token in subsequent calls to get only new messages.
Cached for 30 seconds for near real-time monitoring.
Args:
video_id: YouTube video ID of the live stream.
max_results: Maximum messages to return (1-2000, default 200).
page_token: Pagination token from previous call (None for first call).
Returns:
Dictionary with:
- video_id: YouTube video ID
- messages: List of messages with author, text, published_at, author_channel_id
- total_returned: Number of messages in this response
- next_page_token: Token for next page (None if no more)
- polling_interval_millis: YouTube's recommended polling interval
Example:
>>> # First call - get latest messages
>>> result = get_live_chat_messages("dQw4w9WgXcQ", max_results=50)
>>> print(f"Got {result['total_returned']} messages")
>>>
>>> # Second call - get only new messages since first call
>>> result2 = get_live_chat_messages(
... "dQw4w9WgXcQ",
... max_results=50,
... page_token=result["next_page_token"]
... )
Note:
- Costs 1 quota unit per request
- Cached for 30 seconds in youtube.comments namespace
- Polling Pattern:
1. First call: No page_token → Get latest messages + next_page_token
2. Store next_page_token
3. Subsequent calls: Pass page_token → Get only NEW messages
4. Repeat step 3 every 30-60 seconds for continuous monitoring
- MCP Limitation: Agent must manually call this tool repeatedly to see new messagesCaching Behavior:
Parameters that accept reference strings can accept a
ref_idfrom a previous tool callLarge results return ref_id + preview; use get_cached_result to paginate
All responses include ref_id for future reference
Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.
Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.
Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | ||
| page_token | No | ||
| max_results | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||