Browse documentation
Guides
Find relevant videos, select caption tracks and process new channel uploads without repeating work.
On this page
Start with the information you already have
Each source answers a different question. Skip discovery for a known video ID or channel handle, and enrich only the videos your task needs.
| Your task | Source | Decision |
|---|---|---|
| Find videos about a topic | youtube_search | Start with five candidates, then select by relevance. |
| Inspect a known video | youtube_metadata | Get title, channel, duration and caption languages. |
| Summarize or cite what was said | youtube_transcript / youtube_captions | Choose a language and an automatic or manual track. |
| Check recent channel uploads | youtube_channel | Compare returned IDs with your processed IDs. |
Run the request examples
Save each JSON body using its displayed filename. Python uses the query.py helper below; cURL can submit the same file. Use a key with the source permissions you need and available credits. Each submission is one query, regardless of the number of returned videos.
Python 3.10+. Install requests once, save query.py below, then use the command beside each request. Existing outputs are reused; changed input requires a new output filename.
python -m pip install requestsBash. Replace REQUEST.json and RESULT.json with the filenames for your chosen example. Check the result before repeating a request; this command saves the HTTP body even for an error.
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e RESULT.json || { echo 'Read RESULT.json first'; exit 1; }
curl --fail-with-body --silent --show-error --max-time 70 \
--request POST 'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @REQUEST.json --output RESULT.json
)Set your API key
Reuse FLASHDATA_API_KEY from your terminal or secret store. Otherwise enter the key using one hidden prompt below. Keep it in the process running these examples.
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKeySave query.py for the Python examples
Create query.py in a new working folder and copy the complete code below into it. Save the request JSON files and other Python scripts in this folder, and run all commands from there.
# query.py — submit a saved request once, then reuse its response.
import json
import os
import sys
from pathlib import Path
import requests
if len(sys.argv) != 3:
raise SystemExit("Usage: python query.py REQUEST.json RESULT.json")
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8-sig"))
output = Path(sys.argv[2])
marker = output.with_name(output.name + ".request.json")
receipt = output.with_name(output.name + ".http.json")
if marker.exists():
if json.loads(marker.read_text()) != payload:
raise SystemExit("Changed request: choose a new output filename.")
if not output.exists() or not receipt.exists():
raise SystemExit("Outcome unknown: check History before resubmitting.")
saved = json.loads(receipt.read_text())
if saved["status"] != 200 or json.loads(output.read_text(encoding="utf-8")).get("status") != "done":
raise SystemExit(f"Saved request failed or incomplete; Retry-After: {saved['retry_after']}. Inspect {output}.")
print(f"Read the saved {output}; no new query submitted.")
raise SystemExit(0)
if output.exists():
raise SystemExit("Output already exists. Read it or choose a new filename.")
key = os.environ["FLASHDATA_API_KEY"]
with marker.open("x", encoding="utf-8") as file:
json.dump(payload, file)
response = requests.post("https://data.flashdata.dev/v1/queries/realtime",
headers={"X-API-Key": key}, json=payload,
timeout=70, allow_redirects=False)
output.write_text(response.text, encoding="utf-8")
receipt.write_text(json.dumps({"status": response.status_code,
"retry_after": response.headers.get("Retry-After")}), encoding="utf-8")
if response.status_code != 200:
raise SystemExit(f"HTTP {response.status_code}; Retry-After: {response.headers.get('Retry-After')}")
if response.json().get("status") != "done":
raise SystemExit(f"Inspect {output} and History before retrying.")
print(json.dumps({"saved": str(output), "usage": response.json().get("usage")}, indent=2))Find candidates before fetching details
The video filter excludes other result types; subtitles narrows discovery to videos with captions. It does not select a caption language or guarantee the track you need. Save as discover-request.json.
{
"source": "youtube_search",
"query": "battery recycling process explained",
"params": {
"max_results": 5,
"filters": {
"type": "video",
"subtitles": true
}
}
}python query.py discover-request.json search.jsonSelect by relevance, not the first ID
Save candidates.py beside query.py and search.json, then run it from that folder. It keeps search order and removes duplicate video IDs. Inspect titles, channels and duration, then copy a selected ID into the next request. An empty list is a completed search with no candidates.
# candidates.py — read a saved response; no API calls.
import json
import re
from pathlib import Path
data = json.loads(Path("search.json").read_text(encoding="utf-8"))
if data.get("status") != "done":
raise SystemExit("Search did not complete; inspect search.json.")
candidates, seen = [], set()
for item in (data.get("results") or [{}])[0].get("results", []):
video_id = item.get("videoId", "")
if not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id) or video_id in seen:
continue
seen.add(video_id)
candidates.append({"videoId": video_id, "title": item.get("title"),
"channel": item.get("channel"), "duration": item.get("duration"),
"url": "https://www.youtube.com/watch?v=" + video_id})
Path("candidates.json").write_text(json.dumps(candidates, indent=2), encoding="utf-8")
print(json.dumps(candidates, indent=2))python candidates.pyExpand only when the shortlist is insufficient
Standard Search supports max_results up to 20. For a broader collection, switch to youtube_search_extended, which supports up to 700 and has separate pricing. This example asks for 50; check whether your first results are useful before enriching them all.
{
"source": "youtube_search_extended",
"query": "battery recycling process explained",
"params": {
"max_results": 50,
"filters": {
"type": "video"
}
}
}python query.py extended-request.json extended.jsonRetrieve only the metadata your feature needs
Replace the sample video_id with your selected ID. Keep formats and chapters disabled for a simple video card or caption-language check. Enable include_chapters for an outline, or include_formats when choosing a media format.
{
"source": "youtube_metadata",
"video_id": "FUfGcZ092b0",
"params": {
"include_formats": false,
"include_chapters": false
}
}python query.py metadata-request.json metadata.jsonInspect available languages
Read results[0].transcriptLanguages before choosing captions. Formats, chapters and languages are fields on the returned video object; the usage record belongs to the outer response.
| Setting | Use it for |
|---|---|
| language | A code from transcriptLanguages, such as en or zh-Hans. This list does not distinguish manual and automatic tracks. |
| auto: true | An existing automatically generated track. |
| auto: false | An existing manually provided track. There is no fallback between the two track types. |
python -m json.tool metadata.jsonChoose the language and track explicitly
Use the same video_id as your metadata request and change language and auto to match the chosen track. youtube_transcript defaults to auto: true; youtube_captions defaults to auto: false. Both retrieve existing captions, not speech-to-text.
{
"source": "youtube_transcript",
"video_id": "FUfGcZ092b0",
"params": {
"language": "en",
"auto": true
}
}python query.py captions-request.json captions.jsonKeep the timestamp with the evidence
Save cite-segments.py beside captions.json and run it from that folder. Use results[0].segments for citations: start and end are seconds. Preserve languageCode and isAutoGenerated with the text. fullText is useful for reading, but does not replace segment timing. If the chosen track is missing, record the gap before deciding whether another query is worthwhile.
import json
from pathlib import Path
response = json.loads(Path("captions.json").read_text(encoding="utf-8"))
if response.get("status") != "done":
raise SystemExit("Inspect captions.json before continuing.")
track = (response.get("results") or [{}])[0]
if not track.get("segments"):
raise SystemExit("No caption evidence was returned.")
for segment in track["segments"][:3]:
url = f"https://www.youtube.com/watch?v={track['videoId']}&t={int(segment['start'])}s"
print(segment["text"], url)python cite-segments.pyProcess only new videos from a known channel
Use a channel handle and a bounded video_limit (1–100). results[0].videos is the returned recent list; videoCount is channel metadata, not the number of returned items. Choose a limit and schedule that cover the uploads you need to observe.
{
"source": "youtube_channel",
"handle": "@TED",
"params": {
"video_limit": 10
}
}python query.py channel-request.json channel.jsonKeep a queue and a completion checkpoint
Save channel-queue.py beside query.py and channel.json, and run it from that folder. Run without arguments to create new-ids.json, then process and save evidence for those IDs. Run --commit only after every queued ID succeeds; a failure leaves the checkpoint unchanged. Use one directory per channel and one worker for this example.
# channel-queue.py — plan first; commit only after every queued video is processed.
import json
import re
import sys
from pathlib import Path
checkpoint = Path("processed-ids.json")
processed = set(json.loads(checkpoint.read_text()) if checkpoint.exists() else [])
queue = Path("new-ids.json")
if sys.argv[1:] == ["--commit"]:
processed.update(json.loads(queue.read_text()))
temporary = checkpoint.with_suffix(".tmp")
temporary.write_text(json.dumps(sorted(processed)), encoding="utf-8")
temporary.replace(checkpoint)
queue.unlink()
print("Checkpoint saved.")
elif sys.argv[1:]:
raise SystemExit("Usage: python channel-queue.py [--commit]")
else:
data = json.loads(Path("channel.json").read_text(encoding="utf-8"))
if data.get("status") != "done":
raise SystemExit("Channel query did not complete.")
ids = dict.fromkeys(video.get("videoId", "") for video in
(data.get("results") or [{}])[0].get("videos", []))
new = [value for value in ids if re.fullmatch(r"[A-Za-z0-9_-]{11}", value)
and value not in processed]
if queue.exists() and json.loads(queue.read_text()) != new:
raise SystemExit("Finish the existing queue before replacing it.")
queue.write_text(json.dumps(new, indent=2), encoding="utf-8")
print(json.dumps(new, indent=2))python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commitStart a fresh channel check deliberately
The query helper reuses a saved response. For the next scheduled check, use a new result filename, inspect it, then copy that completed response to channel.json for the queue step. Keep processed-ids.json between runs. This recent list is not a full-channel export or an event stream.
python query.py channel-request.json channel-next.jsonpython -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"Use suggestions to improve the query
Suggestions return phrases in results[0], not video records. Select a useful phrase and make a separate youtube_search request. Set the language and region for the audience you are researching.
{
"source": "youtube_suggestions",
"query": "battery recycling",
"params": {
"language": "en",
"region": "US"
}
}python query.py suggestions-request.json suggestions.jsonStore license labels without treating them as permission
youtube_trainability returns a license label for a video. permitted: ["all"] maps to Creative Commons; ["none"] also covers missing license metadata. Keep the video ID, source response and retrieval date. This label does not grant download, reuse or training rights.
{
"source": "youtube_trainability",
"video_id": "FUfGcZ092b0"
}python query.py license-request.json license.jsonBound the work for apps and agents
| Rule | Implementation |
|---|---|
| Select before enriching | For a topic task: one search, one selected video's metadata and one chosen caption track. Enforce the call budget in your app, and price each source separately. |
| Reuse by the actual input | Metadata: video ID + options. Captions: video ID + language + track. Channel snapshots also need a retrieval time or run ID. |
| Stop on missing evidence | Do not retry an empty discovery result or silently switch caption tracks. Return the gap so the user or workflow can choose the next action. |
| Preserve usage and failed work | Save usage with successful responses. On 429, honor Retry-After; after an uncertain submission, check History before another paid query. |