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

# Should I call again when my AI shows only a small preview?

> Do not re-run youtube.web_v2.get_video_comments for a short preview; read the local saved JSON or fetch the stored page with operation: result and result_ref.request_id without extra billing.

Usually no. When an assistant displays only a short YouTube comment preview, check first for a locally saved full response or a `result_ref` object in the preview. If you already saved the JSON file locally, read that file directly. If the stored result is still available, retrieve the full stored page with `operation:"result"`, the same `reference`, and `result_ref.request_id`; reading a stored result does not execute or bill the capability again. Use `continuation_token` only when you need the next page from YouTube.

## Diagnose the preview before making another call

| What you actually have                                                  | Correct next step                                                                                                                                   |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| A full saved JSON file, while the chat displays only a snippet          | Read the local JSON file; no platform call is needed.                                                                                               |
| A Run preview with `items`, `items_path`, `truncated`, and `result_ref` | While `result_ref.expires_at` has not passed, retrieve the stored page using `result_ref.request_id` as shown below.                                |
| `result_ref_unavailable` or no `result_ref`                             | Do not assume a cached result exists. Reuse any locally saved file; otherwise decide separately whether to fund a fresh query.                      |
| A full result containing a platform `continuation_token`                | `continuation_token` points to the next YouTube comment page, not the rest of the stored page. Requesting that next page is a separate billed call. |

`items_total` counts only the items detected in the returned response, not every comment on the YouTube video. A Run preview can shorten text inside each item as well as cap the item count, so raising `max_items` on another preview does not confirm that full comment text was read. Check `result_ref.expires_at` for the exact expiry deadline; one-hour retention is temporary rather than a permanent archive.

## Prepare the free stored-result request from the saved preview

1. Save the complete Run preview response as `youtube-preview.json` instead of copying a chat snippet.
2. Save the script below as `saved_result.py`.
3. Run `python3 saved_result.py youtube-preview.json result-request.json`.

`saved_result.py` validates the saved preview locally without making network calls. `saved_result.py` stops if `result_ref` is missing, unavailable, or expired, if the action conflicts with `youtube.web_v2.get_video_comments`, or if `result-request.json` already exists.

```python
import json, pathlib, sys
from datetime import datetime, timezone
preview_path, output_path = map(pathlib.Path, sys.argv[1:3])
preview = json.loads(preview_path.read_text(encoding='utf-8'))
if not isinstance(preview,dict): raise ValueError('Expected saved Run preview object')
if preview.get('result_ref_unavailable'):
    raise ValueError('No retrievable stored result; do not silently start another paid call')
if preview.get('action') not in (None,'youtube.web_v2.get_video_comments'):
    raise ValueError('Preview belongs to another action')
ref=preview.get('result_ref')
if not isinstance(ref,dict): raise ValueError('No result_ref; a small display alone is not a stored-result reference')
rid=ref.get('request_id')
if not isinstance(rid,str) or not rid.strip() or rid != rid.strip(): raise ValueError('Invalid stored request ID')
expires=datetime.fromisoformat(ref['expires_at'].replace('Z','+00:00'))
if expires.tzinfo is None: raise ValueError('Expiry must include timezone')
if expires <= datetime.now(timezone.utc): raise ValueError('Stored result reference has expired; no new start is prepared')
request={'reference':'data:youtube.web_v2.get_video_comments','operation':'result','request_id':rid,'view':'full'}
with output_path.open('x',encoding='utf-8') as f: json.dump(request,f,indent=2)
print(json.dumps({'operation':'result','request_id':rid,'network_calls':0}))

```

Send `result-request.json` using an authorized API key from the same account, normally the key used for the original request:

```bash
mkdir youtube-recovered && \
curl -sS -X POST https://api.beatapi.io/v1/capabilities/run \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d @result-request.json \
  -D youtube-recovered/response.headers -o youtube-recovered/result.json
```

The `mkdir` guard prevents an existing output directory from being overwritten by a cache error. For another retrieval attempt, pick a new directory name and preserve earlier files. The request sets `operation:"result"` and `view:"full"` without `input`, `fields`, or a preview cap, so BeatAPI reads the stored response body without executing or billing the capability again. Save both HTTP response headers and JSON because an error body is not a comment dataset. Stored-result recovery applies to Capabilities Run `result_ref` entries; direct `/v1/social-data/call` responses are not necessarily cached.

## What if the response says the result expired?

1. Verify that the request uses `result_ref.request_id`, an API key for the same account, and an unexpired `result_ref.expires_at` timestamp.
2. Stored results can also be unavailable or evicted, and the stored-result cache does not retain response bodies larger than 2 MiB.
3. `result_ref_unavailable` means no retrievable cache entry was created; retrying `operation:"result"` does not make an entry appear.
4. Do not fall back automatically to `operation:"start"`. Keep the error response, the original query, and any saved full file, then decide separately whether to fund a fresh query.

A failed cache lookup does not mean the YouTube video has zero comments, and recovering a stored page does not fetch the next platform page or comment replies. Executing `youtube.web_v2.get_video_comments` costs `$0.003` per executed data request, while reading a stored result with `operation:"result"` is not billed as another execution.

[Comment research](/guides/youtube-review-questions) · [Capabilities result contract](/capabilities) · [YouTube questions](/faq/youtube)

Free action contract: `data:youtube.web_v2.get_video_comments`.