Skip to content
EN
Get API key
Browse documentation

API reference

YouTube Search API

Get an API key

Search YouTube videos by keyword and retrieve titles, channels, durations, view counts and thumbnails as JSON.

Build a request

Maximum number of search results to return.

Advanced parameters
Features
POSThttps://data.flashdata.dev/v1/queries/realtime
Python 3 · requests
python3 -m pip install requests
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_search",
    "query": "python",
    "params": {
        "max_results": 20,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key, "Accept": "application/json"},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
Results in the HTTP responseX-API-Key authentication

Parameters

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.
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 20, 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.
true or falseDefault: Not set
params.filters.3dboolean / Optional
Set true to require the 3d feature.
true or falseDefault: Not set
params.filters.4kboolean / Optional
Set true to require the 4k feature.
true or falseDefault: Not set
params.filters.creative_commonsboolean / Optional
Set true to require the creative commons feature.
true or falseDefault: Not set
params.filters.hdboolean / Optional
Set true to require the hd feature.
true or falseDefault: Not set
params.filters.hdrboolean / Optional
Set true to require the hdr feature.
true or falseDefault: Not set
params.filters.liveboolean / Optional
Set true to require the live feature.
true or falseDefault: Not set
params.filters.locationboolean / Optional
Set true to require the location feature.
true or falseDefault: Not set
params.filters.purchasedboolean / Optional
Set true to require the purchased feature.
true or falseDefault: Not set
params.filters.subtitlesboolean / Optional
Set true to require the subtitles feature.
true or falseDefault: Not set
params.filters.vr180boolean / Optional
Set true to require the vr180 feature.
true or falseDefault: 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 is the number returned, not YouTube's total matching catalog.

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.

read-response.py
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 20. Extended Search supports up to 700 with a separate usage rate.

Filters belong in params.filters, not beside params. Omit filters to use YouTube's default behavior. Returned item details depend on result type and availability.

All response fields
FieldDescription
sourcestringThe requested API source.
statusstringdone when the realtime request succeeds.
created_atstringResponse creation time in ISO 8601 format.
usage.creditsnumberCredits charged for the request, based on your plan.
results[0].querystringThe search query.
results[0].totalResultsintegerNumber of results returned.
results[0].resultsarraySearch results in their returned order.
results[0].results[].videoIdstringYouTube video ID.
results[0].results[].titlestringVideo title.
results[0].results[].channelstringChannel name.
results[0].results[].channelIdstring · nullableChannel ID when available.
results[0].results[].channelUrlstring · nullableChannel URL when available.
results[0].results[].durationnumber · nullableVideo duration in seconds.
results[0].results[].durationStringstring · nullableFormatted video duration when available.
results[0].results[].viewCountnumber · nullableView count when available.
results[0].results[].uploadDatestring · nullableUpload date when available.
results[0].results[].descriptionstring · nullableDescription excerpt, up to 500 characters, or null when unavailable.
results[0].results[].thumbnailsarrayThumbnail 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. 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.

    Async request and receipt · Batch request body

  2. 2. Check status

    GET https://api.flashdata.dev/v2/jobs/{jobId}

    pending / processing: poll with a delay and respect Retry-After when present. completed: fetch results. failed: inspect job.error.

    Read job.status, not the submission receipt's status.

    Check status · Python and cURL

    Job status API reference
  3. 3. Fetch results

    GET https://api.flashdata.dev/v2/jobs/{jobId}/results

    After 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
Illustrative completion notification
{
  "delivery_id": "completion:job_example0001",
  "id": "job_example0001",
  "source": "youtube_search",
  "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"
    }
  ]
}
FieldDescription
delivery_idstringStable delivery identifier. Deduplicate notifications using this value; it is also sent in the X-Delivery-Id header.
idstringJob ID.
sourcestringRequested data source.
statusstringcompleted or failed.
linksarrayStatus and result links. Notifications do not include result content or an API key.
links[].relstringself or results.
links[].hrefstringAbsolute Management API URL; authenticate with your API key.
links[].methodstringGET.

Full webhook contract and URL restrictions

Error recovery

A successful search may return fewer items than requested. Relax filters or adjust the query before submitting another request; an empty result is not itself a job failure.

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.

Errors and status codes · When to retry · Rate limits

Step-by-step guide: Find videos for a topic

Pricing

PlansUsage ratesper 1,000 standard requestsSubscriptionsIncluded credits per billing period
Pay as you go$0.50No monthly feeTop up as needed
Micro$0.40$49.00 / month1,000 credits ($50.00 of API usage) included
Starter$0.35$199.00 / month4,000 credits ($200.00 of API usage) included
Pro$0.30$499.00 / month10,000 credits ($500.00 of API usage) included
Scale$0.25$999.00 / month20,000 credits ($1,000.00 of API usage) included
Business$0.20$1,999.00 / month40,000 credits ($2,000.00 of API usage) included

One account plan. Shared Credits across all three products. Usage covered by included credits is not charged again.

Current prices and plan limits