Browse documentation
API reference
YouTube Extended Search API
Retrieve up to 700 YouTube search results per request, with video details, thumbnails and search filters.
Build a request
Maximum number of search results to return.
Advanced parameters
https://data.flashdata.dev/v1/queries/realtimeParameters
Send source and query at the top level. Source options belong in params. Optional fields can be omitted.
Request body
sourcestring / Required- Set to youtube_search_extended.
querystring / Required- Search query.1 to 2,000 charactersDefault:
Not set paramsobject / Optional- Settings for this request.Default:
{} callback_urlstring · nullable / Optional- Async and batch only. Public HTTPS completion URL on port 443, up to 2,048 characters. No user credentials or URL fragment. Omit, use null or an empty string for no notification. In a batch, set this on each query, outside params.Default:
Not set
Result count
params.max_resultsinteger / Optional- Requested result count. Fewer results may be available.1 to 700, whole numbersDefault:
20
Search filters
params.filtersobject · nullable / Optional- Optional upload date, result type, duration, sorting and feature filters. Omit or use null for no filters.Default:
Not set params.filters.upload_datestring / Optional- Filter by upload date.1 to 2,000 charactersValues:
today / last_hour / this_week / this_month / this_yearDefault:Not set params.filters.typestring / Optional- Filter by result type.1 to 2,000 charactersValues:
video / channel / playlist / movieDefault:Not set params.filters.durationstring / Optional- Filter by video duration in minutes.1 to 2,000 charactersValues:
<4 / 4-20 / >20Default:Not set params.filters.sort_bystring / Optional- Result ordering. Omit to use YouTube's default ordering.1 to 2,000 charactersValues:
rating / relevance / view_count / upload_dateDefault:Not set params.filters.360boolean / Optional- Set true to require the 360 feature.
trueorfalseDefault:Not set params.filters.3dboolean / Optional- Set true to require the 3d feature.
trueorfalseDefault:Not set params.filters.4kboolean / Optional- Set true to require the 4k feature.
trueorfalseDefault:Not set params.filters.creative_commonsboolean / Optional- Set true to require the creative commons feature.
trueorfalseDefault:Not set params.filters.hdboolean / Optional- Set true to require the hd feature.
trueorfalseDefault:Not set params.filters.hdrboolean / Optional- Set true to require the hdr feature.
trueorfalseDefault:Not set params.filters.liveboolean / Optional- Set true to require the live feature.
trueorfalseDefault:Not set params.filters.locationboolean / Optional- Set true to require the location feature.
trueorfalseDefault:Not set params.filters.purchasedboolean / Optional- Set true to require the purchased feature.
trueorfalseDefault:Not set params.filters.subtitlesboolean / Optional- Set true to require the subtitles feature.
trueorfalseDefault:Not set params.filters.vr180boolean / Optional- Set true to require the vr180 feature.
trueorfalseDefault:Not set
Response
Realtime returns status: done. Read the source output at results[0].results; usage.credits records the charge.
Search output contains query, totalResults and the returned items. totalResults counts this response's items; it is not the total number of matching videos on YouTube.
Read the result
Save the successful JSON response as response.json. Save this as read-response.py and run python read-response.py. It uses only Python's standard library and makes no new request.
import json
from pathlib import Path
response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
print("[]")
raise SystemExit(0)
result = response["results"][0]
output = [
{"videoId": item.get("videoId"), "title": item.get("title"), "channel": item.get("channel")}
for item in result.get("results", [])
]
print(json.dumps(output, ensure_ascii=False, indent=2))max_results defaults to 20 and accepts 1 to 700. This is one larger search request, not 700 separate batch jobs. Larger requests can take longer; async avoids keeping the submitter's connection open.
Filters belong in params.filters. Fewer results may be available, and rich item fields can be null or absent. Extended Search has its own usage rate.
All response fields
| Field | Description |
|---|---|
sourcestring | The requested API source. |
statusstring | done when the realtime request succeeds. |
created_atstring | Response creation time in ISO 8601 format. |
usage.creditsnumber | Credits charged for the request, based on your plan. |
results[0].querystring | The search query. |
results[0].totalResultsinteger | Number of results returned. |
results[0].resultsarray | Search results in their returned order. |
results[0].results[].videoIdstring | YouTube video ID. |
results[0].results[].titlestring | Video title. |
results[0].results[].channelstring | Channel name. |
results[0].results[].channelIdstring · nullable | Channel ID when available. |
results[0].results[].channelUrlstring · nullable | Channel URL when available. |
results[0].results[].durationnumber · nullable | Video duration in seconds. |
results[0].results[].durationStringstring · nullable | Formatted video duration when available. |
results[0].results[].viewCountnumber · nullable | View count when available. |
results[0].results[].uploadDatestring · nullable | Upload date when available. |
results[0].results[].descriptionstring · nullable | Description excerpt, up to 500 characters, or null when unavailable. |
results[0].results[].thumbnailsarray | Thumbnail URLs and dimensions. |
The fields above describe the default JSON response. JSON, plain text and Markdown formats.
Async returns one job receipt; batch returns one per query. Check each job's status and retrieve its results using the returned links.
Async & batch lifecycle
Submission returns a receipt, not results. Async creates one job; batch returns a separate job in queries[] for every accepted query. Track and retrieve each job independently.
Submit to data.flashdata.dev; read job status and results from api.flashdata.dev with the same X-API-Key. The linked API basics examples use Python and cURL.
1. Save the job IDs
Keep this source's request fields when switching to Async. For Batch, put each request inside the queries array of a JSON object. Save every returned job ID.
2. Check status
GET https://api.flashdata.dev/v2/jobs/{jobId}pending/processing: poll with a delay and respectRetry-Afterwhen present.completed: fetch results.failed: inspectjob.error.Read job.status, not the submission receipt's status.
Check status · Python and cURL
Job status API reference3. Fetch results
GET https://api.flashdata.dev/v2/jobs/{jobId}/resultsAfter completion, authenticate the result read, then fetch the 302 storage URL without your API key. Save the JSON within 24 hours of completion.
Fetch results · Python and cURL · Response formats
Result download API reference
Polling and fetching existing results do not consume query credits. A polling timeout does not cancel the job: keep its ID instead of submitting duplicate billable work. Error codes and retry behavior.
Completion webhooks
Subscribe per query
Set callback_url at the top level of an async request, or inside each query in a batch, outside params. No separate webhook-registration request is required. Realtime requests do not send callbacks.
Use a public HTTPS URL on port 443. FlashData POSTs a notification for each job reaching completed or failed; the event contains links, not the result itself.
Acknowledge and verify
Return 2xx after durably accepting the event. Deduplicate by delivery_id, also sent as X-Delivery-Id. Redirects are not followed.
Failed deliveries retry with exponential backoff, up to 8 attempts total and at most 24 hours after completion. Keep polling as a fallback.
Callbacks are unsigned. Confirm the job ID, source and terminal status through the authenticated status endpoint before processing the notification. The delivery ID is for deduplication, not proof of authenticity.
Example webhook event and fields
{
"delivery_id": "completion:job_example0001",
"id": "job_example0001",
"source": "youtube_search_extended",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
"method": "GET"
}
]
}| Field | Description |
|---|---|
delivery_idstring | Stable delivery identifier. Deduplicate notifications using this value; it is also sent in the X-Delivery-Id header. |
idstring | Job ID. |
sourcestring | Requested data source. |
statusstring | completed or failed. |
linksarray | Status and result links. Notifications do not include result content or an API key. |
links[].relstring | self or results. |
links[].hrefstring | Absolute Management API URL; authenticate with your API key. |
links[].methodstring | GET. |
Error recovery
If a large realtime request times out, acceptance may be uncertain. Check job history before resubmitting. For subsequent large searches, choose async and track the returned ID.
For authentication, balance, request-format and rate-limit failures, use the shared error reference. A submission timeout may still have created a job; check existing work before retrying.
Step-by-step guide: Plan a larger candidate search