Skip to content
truescrape
Free key

Contents

Site

YouTube Search API

Open in ChatGPTOpen in ClaudeOpen in Gemini

Public YouTube search results for a query: videos and Shorts in YouTube’s ranking order, with a cursor for the next page. Calls cost 1 credit each. A cache hit is free, and a failed or empty response is never charged.

Try it

Prefilled with the request that produced the example below. No key yet? Get a free key.

Request

GET/v1/youtube/search
ParameterTypeRequiredDescription
querystringyes—
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/search?query=nasa%20artemis&cache_max_age=7d" \
  -H "x-api-key: $KEY"
JavaScript
const query = new URLSearchParams({
  query: 'nasa artemis',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/search?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/search",
    params={
        "query": "nasa artemis",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])

Example response

Captured on , with raw removed and lists cut to two items. A live call returns current data.

response
{
  "success": true,
  "data": {
    "items": [
      {
        "platform": "youtube",
        "id": "jfeVornFhxg",
        "type": "video",
        "url": "https://www.youtube.com/watch?v=jfeVornFhxg",
        "title": "Is this the NASA Artemis lunar landing schedule that Blue Origin and SpaceX finally meet?",
        "text": "As it turns out, there is an Artemis lunar lander update before the live broadcast one this Friday. The NASA quietly published two ...",
        "authorId": "example-user-1",
        "authorHandle": "example_user_1",
        "authorName": "Example User 1",
        "thumbnailUrl": "https://example.com/media/1.jpg",
        "mediaUrls": [],
        "durationSeconds": 812,
        "viewCount": 1772,
        "likeCount": null,
        "commentCount": null,
        "shareCount": null,
        "hashtags": [],
        "mentions": [],
        "isSponsored": null,
        "publishedAt": null,
        "fetchedAt": "2026-10-21T01:55:27.137Z"
      },
      {
        "platform": "youtube",
        "id": "Zezt6EsG9WE",
        "type": "video",
        "url": "https://www.youtube.com/watch?v=Zezt6EsG9WE",
        "title": "NASA Moon Base: Rovers and Lunar Terrain Vehicles (October 2026 Update)",
        "text": "There's a lot of ground to cover when you're building a Moon Base. From robotic rovers exploring the rugged lunar landscape to ...",
        "authorId": "UCLA_DiR1FfKNvjuUpBHmylQ",
        "authorHandle": "NASA",
        "authorName": "NASA",
        "thumbnailUrl": "https://i.ytimg.com/vi/Zezt6EsG9WE/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLD89hXnM_XZRxc5qbhG2g_q050geQ",
        "mediaUrls": [],
        "durationSeconds": 558,
        "viewCount": 115279,
        "likeCount": null,
        "commentCount": null,
        "shareCount": null,
        "hashtags": [],
        "mentions": [],
        "isSponsored": null,
        "publishedAt": null,
        "fetchedAt": "2026-10-21T01:55:27.137Z"
      }
    ]
  },
  "pagination": {
    "cursor": "eyJ0IjoiRXRnREVneHVZWE5oSUdGeWRHVnRhWE1heEFOVFFsTkRRVkpvVmxFd2VFSllNRkp3VldwR1IxcHJkRTlrYlhBeFZsaENRMU5ITVRWaVJrZERRVkYwY1ZwdFZsZGlNMHAxVW0xb05GbzBTVUpETVhCc1pXNVJNbEpZVGtoUFZtUkdaMmRGVEZNeVZUSlhSbWMwVW10b1VGTkZNa05CVVhSb1pIcHNSbFJyYkVKalYzUkNUMGxKUWtsc1FrMU5iVVpEVjI1V1JGcFZVak5pUmtZeVZHNVNTV0ZGTlV0a1IwWjVZbFJzVUZwWVpGSmtNVnAxWkVoaFEwRlJkR1pXUkdocVltcEtTMDFVVFhST1NVbENRekU1YkZwV2NGSmtlbXhSVVcxTmQyZG5SVXhpYlZwdlVraFdVRk5GTVhkTlJVZERRVkYwVjFwNU1VWlZWR1JPVkROVk1sTlpTVUpEZVRGYVZHeHdjRmxZVGxOU2VrSlNaMmRGVEU0eGFEWmhTRkpZV1RKV2QySXpUME5CVVhSSlRtcGFWRlpGVlhoTk1VSTBWbGxKUWtNemNFOWthbVIyVDBoa1JsTnRVbXBuWjBWTVRtNVdVR05ZUmxGa1dFSlVaVlZIUTBGUmREWlpNMUpWVXpKU1Vsa3lNVmRSV1VsQ1F6SkdlRnByTlVWWGJYaElZMjVDYW1kblJVeGpWV3hUVWtka2RVOVhTakJTVlRKRFFWRjBRMWg2WkVaV1Z6RkVaVWRPTWxKWlNVSkRNVkp0V0RGV2NWRnJNVXBsYXpWMmMyZEZSME5uVVVsR2FFRkRObWRGUlVOQlNWRkhVU1V6UkNVelJLQUNCQmlCNE9nWUlndHpaV0Z5WTJndFptVmxaQSUzRCUzRCIsInYiOiJDZ3N3VDJaTVZITnpYMFZtVVNpT3QtRFdCaklLQ2dKRVJSSUVFZ0FnVUdLekFncXdBa04xUlVKRFFWVlRhM2RGUWpoUlduVmFjMHcwVmtwb1psODFhRGxwWldKUlRrVmlSMHRNYURFdFpUbExabUpTZFd4ek9GZHlNbTVIWkhkWWVVNHlZamxmYm1OMVpIRTNRbWhCWVhkMU5EazFTbVJLZVRCM1VuZFRlVWhSVUdoeWMxazBTVWxGTUU5T2QzRmFVelJIVVVFemRrbHVabUZ4Wm5odE0wdExNbUZHWkRWUmNGUjBSVXQzZG5oVlVIRmxkRjg1WlVKTVJGVk1TSEJ1UTBKd2RETkdOME5UYWxkaWRHUjNTWEpmY2w5cWQwTnJja3RxY1d0VmJDMXZaVUp2VEZwSFNrdHRNbXAyVDJVME5YQXpiMjlDVkVwR1FXUTJjRzVWWHpWcVZrYzFkVGQzVUVwcUxVdHpSWFY1T0hsSU5sOVRWMmxMYkhneldXMVRPWGN0VmxWQlZtNUZRV3BYYVVSZlYwMUVaVkpsVEhkUmRuTXRMVzQyUW1zNVRsQm5YelYwV1RJeFQyUjNXVzE0VTBsdFRVMCUzRCJ9",
    "hasMore": true,
    "count": 43
  },
  "meta": {
    "platform": "youtube",
    "endpoint": "youtube.search",
    "creditsCharged": 1,
    "cached": false,
    "cacheAgeSeconds": null,
    "durationMs": 528,
    "requestId": "req_3w24wldd6ljrt1r5pvhv"
  }
}

Returns

Returns a list of Post in data.items.

Cost and behaviour

Credits1 per live request, 0 on a cache hit
Cacheableyes: cache_max_age accepts a cached copy
Batchableyes: usable as a target in POST /v1/jobs/batch
Subscribableno

Other YouTube endpoints

All YouTube endpointsThe unified schema