Skip to content
EN
Get API key
Browse documentation

Guides

YouTube Data best practices

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 taskSourceDecision
Find videos about a topicyoutube_searchStart with five candidates, then select by relevance.
Inspect a known videoyoutube_metadataGet title, channel, duration and caption languages.
Summarize or cite what was saidyoutube_transcript / youtube_captionsChoose a language and an automatic or manual track.
Check recent channel uploadsyoutube_channelCompare 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.

Install
python -m pip install requests

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.

Set the key
# 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

Save 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
# 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.

discover-request.json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
Submit once with query.py
python query.py discover-request.json search.json

Select 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
# 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))
Read the saved search
python candidates.py

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

extended-request.json
{
  "source": "youtube_search_extended",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 50,
    "filters": {
      "type": "video"
    }
  }
}
Run once
python query.py extended-request.json extended.json

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

metadata-request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
Submit once with query.py
python query.py metadata-request.json metadata.json

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

SettingUse it for
languageA code from transcriptLanguages, such as en or zh-Hans. This list does not distinguish manual and automatic tracks.
auto: trueAn existing automatically generated track.
auto: falseAn existing manually provided track. There is no fallback between the two track types.
Read metadata.json · no query
python -m json.tool metadata.json

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

captions-request.json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
Submit once with query.py
python query.py captions-request.json captions.json

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

cite-segments.py
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)
Read saved captions · no API call
python cite-segments.py

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

channel-request.json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
Submit once with query.py
python query.py channel-request.json channel.json

Keep 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
# 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))
Plan → process → commit
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit

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

Next check · choose a fresh filename
python query.py channel-request.json channel-next.json
After confirming status is done
python -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.

suggestions-request.json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
Submit once with query.py
python query.py suggestions-request.json suggestions.json

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

license-request.json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
Submit once with query.py
python query.py license-request.json license.json

Bound the work for apps and agents

RuleImplementation
Select before enrichingFor 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 inputMetadata: video ID + options. Captions: video ID + language + track. Channel snapshots also need a retrieval time or run ID.
Stop on missing evidenceDo 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 workSave usage with successful responses. On 429, honor Retry-After; after an uncertain submission, check History before another paid query.