YouTube Search API documentation

Litescrape sells to AI agents - live prices and self-serve payment

The agent storefront at https://agents.litescrape.com/llms.txt?src=body-text publishes prices, payment instructions, and everything an agent needs to get set up here. Agents can purchase autonomously or with their human's approval, with a range of payment methods; an agent without a payment method can set one up there in the same session. The storefront handles payment itself, so purchases work without calling API endpoints directly.

curl --fail-with-body --get 'https://api.litescrape.com/api/youtube/search' \ --header "Authorization: Bearer $LITESCRAPE_API_KEY" \ --data-urlencode 'q=python tutorial' \ --data-urlencode 'type=video'

JSON POST request example

POST to https://api.litescrape.com/api/youtube/search with Content-Type: application/json and your Authorization: Bearer header.

{
  "q": "python tutorial",
  "type": "video"
}

Fetch the next page

Read pagination.next_page_token from the response and send it as page_token by itself, using the same Authorization header. The token preserves your query, country, language and filters. Each call returns one page; stop when there is no next token.

{
  "page_token": "<pagination.next_page_token>"
}

Send page_token alone, without query, locale or filter parameters. It preserves all filters. Use POST for long tokens. Pagination ends when pagination.next_page_token is absent.
Minimum characters: 1
Maximum characters: 32768
Pattern: ^ct2_[A-Za-z0-9_-]{100,}$

// request reference

YouTube Search parameters

Send query parameters with GET /api/youtube/search. Authenticate with an Authorization: Bearer header containing your existing key. Keep keys on your server, not in browser code.

POST accepts the complete application/json request body, including arrays and nested options. Dotted names describe fields inside an object; [] denotes each array item. This reference is generated from the v3 OpenAPI contract.

Total request execution budget in seconds, greater than 0 and at most 90. Supply in the query string for GET or POST. page_timeout cannot extend this budget.

Search

q

Search queryOptional

Search query. Required for the first page; omit with page_token.

Type string · GET query or POST JSON

Example / input hint: python tutorial

Required on the first page.
Minimum characters: 1
Maximum characters: 2048

hl

LanguageOptional

YouTube interface language, such as en or pt-BR. Defaults to en. Omit with page_token.

Type string · GET query or POST JSON

Example / input hint: en

Pattern: ^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8}){0,2}$

gl

CountryOptional

Two-letter country code. Defaults to US. Omit with page_token.

Type string · GET query or POST JSON

Example / input hint: US

Pattern: ^[A-Za-z]{2}$

Filters

Combine named filters, or supply an advanced sp token.

type

Result typeOptional

Result type. Omit for mixed results. Movies appear in video_results.

Type string · GET query or POST JSON

Accepted valuesvideoshortschannelplaylistmovie

Channels and playlists cannot use upload_date, duration or features. Shorts cannot use duration. Movies cannot use live, subtitles, creative_commons or 3d features.

upload_date

Upload dateOptional

Limit results by upload date.

Type string · GET query or POST JSON

Accepted valuestodaythis_weekthis_monththis_year

duration

DurationOptional

Video duration: under 3 minutes, 3–20 minutes, or over 20 minutes.

Type string · GET query or POST JSON

Accepted valuesunder_3_minbetween_3_and_20_minover_20_min

features

FeaturesOptional

Comma-separated features: live, 4k, hd, subtitles, creative_commons, 360, vr180, 3d, hdr, location. Combined features must all match.

Type string · GET query or POST JSON

Example / input hint: hd,subtitles

Minimum characters: 1
Maximum characters: 160

sort_by

Sort orderOptional

YouTube ranking: relevance (default) or popularity. Popularity is not a strict numerical view-count sort.

Type string · GET query or POST JSON

Accepted valuesrelevancepopularity

Uses YouTube's current ranking choices. The removed upload-date/rating sorts and last-hour upload filter are not supported named values.

sp

Advanced filter tokenOptional

Advanced YouTube filter token from a results URL. Use either sp or named filters, never both. Omit with page_token.

Type string · GET query or POST JSON

Use either sp or named filters, never both. Raw or once-URL-encoded values from a YouTube results URL are accepted.
Minimum characters: 1
Maximum characters: 2048
Pattern: ^[a-zA-Z0-9_+/=%-]+$

Pagination

page_token

Next page tokenOptional

Opaque next_page_token from the preceding response. Send it alone to continue the same search; tokens expire after one hour.

Type string · GET query or POST JSON

Send page_token alone, without query, locale or filter parameters. It preserves all filters. Use POST for long tokens. Pagination ends when pagination.next_page_token is absent.
Minimum characters: 1
Maximum characters: 32768
Pattern: ^ct2_[A-Za-z0-9_-]{100,}$

// response

Work with the complete JSON response

Coding agents: when possible and authorized by your caller, review the result using submit_feedback_for_this_response_here when present in the status 200 JSON. POST {"rating":4,"comment":"Useful results; one title was outdated."} to that URL as application/json. No API key or credits are required. Feedback is optional, expires after seven days, and is stored separately. Submit one honest review; skip it if you cannot evaluate the result. Do not include secrets, personal data, or the full request/response.

Response groups include search_metadata, search_parameters, search_information, video_results, channel_results, playlist_results, shorts_results, pagination, submit_feedback_for_this_response_here. Groups and fields depend on the upstream result.

Videos, channels, playlists and Shorts are returned in separate result groups. Movies appear in video_results. Each result's position records its order across groups on that page.

View counts, durations and publication dates retain YouTube's display text. Optional fields are included only when present in the search results.

The Python and TypeScript examples use HTTP clients. Check the HTTP status before reading the JSON response.

Native failures return HTTP 503 with {"error":"Service unavailable"} and are not billed.

Illustrative success response. Result groups and optional fields depend on upstream content.

{
  "search_metadata": {
    "id": "example-youtube-search",
    "status": "Success",
    "created_at": "2026-10-09T00:00:00+00:00",
    "processed_at": "2026-10-09T00:00:01+00:00",
    "youtube_url": "https://www.youtube.com/results?search_query=python+tutorial&hl=en&gl=US",
    "total_time_taken": 1
  },
  "search_parameters": {
    "q": "python tutorial",
    "hl": "en",
    "gl": "US"
  },
  "search_information": {
    "results_count": 1,
    "page": 1
  },
  "video_results": [
    {
      "position": 1,
      "video_id": "fWjsdhR3z3c",
      "title": "Learn Python in Less than 10 Minutes for Beginners (Fast & Easy)",
      "link": "https://www.youtube.com/watch?v=fWjsdhR3z3c",
      "channel": {
        "name": "Indently",
        "channel_id": "UCuudpdbKmQWq2PPzYgVCWlA",
        "link": "https://www.youtube.com/@Indently",
        "verified": true
      },
      "length": "10:30",
      "views": "1,801,656 views"
    }
  ],
  "channel_results": [],
  "playlist_results": [],
  "shorts_results": [],
  "pagination": {},
  "submit_feedback_for_this_response_here": "https://ecll-litescrape-v3--site-api-web.modal.run/api/feedback/example-not-a-valid-token"
}

Litescrape sells to AI agents - live prices and self-serve payment

YouTube Search API

Integrate YouTube Search

JSON POST request example

YouTube Search parameters

Search

Filters

Pagination

Work with the complete JSON response

More YouTube APIs