Search

GET/v1/youtube/search1 credit

Searches YouTube and returns matching videos, channels, playlists and Shorts.

01Query parameters

Name	Type	Description
queryrequired	string	Search terms.
uploadDateoptional	string	Only results uploaded in this period. Any other value is a 400.Accepted values:`todaythis_weekthis_monththis_year`
sortByoptional	string	Sort order; `popular` sorts by view count.Default: `relevance`Accepted values:`relevancepopular`
typeoptional	string	Only this kind of result.Accepted values:`videosshortschannelsplaylists`
durationoptional	string	Video length filter.Accepted values:`under_3_minbetween_3_and_20_minover_20_min`
regionoptional	string	Two-letter country code that sets the YouTube region for the request (e.g. `US`, `GB`).Default: `US`
continuationTokenoptional	string	The `continuationToken` from the previous page.

02Request

curl "https://api.scrapesocial.ai/v1/youtube/search?query=mrbeast" \
  -H "x-api-key: $SCRAPESOCIAL_KEY"

03Responses

Real answers from the API. Lists are shortened to 2 items.

GET /v1/youtube/search?query=mrbeast

{
  "success": true,
  "credits_remaining": 4980,
  "credits_charged": 1,
  "videos": [
    {
      "type": "video",
      "id": "RE3_PGwDwhw",
      "url": "https://www.youtube.com/watch?v=RE3_PGwDwhw",
      "title": "Lose 150 Lbs Together, Win $250,000",
      "thumbnail": "https://i.ytimg.com/vi/RE3_PGwDwhw/hq720_custom_1.jpg?sqp=CLzt-NYG-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLBBCS1RVFaP4q52yIqsnGv_DxZYTQ",
      "channel": {
        "id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
        "title": "MrBeast",
        "handle": "MrBeast",
        "thumbnail": "https://yt3.ggpht.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJzXrnJiuDE=s68-c-k-c0x00ffffff-no-rj"
      },
      "viewCountText": "148,555,689 views",
      "viewCountInt": 148555689,
      "publishedTimeText": "8 days ago",
      "publishedTime": "2026-10-17T17:07:18.906Z",
      "lengthText": "43:17",
      "lengthSeconds": 2597,
      "badges": [
        "CC"
      ]
    },
    {
      "type": "video",
      "id": "plN7JMbadRg",
      "url": "https://www.youtube.com/watch?v=plN7JMbadRg",
      "title": "Eat Everything In A Grocery Store, Win $1,000,000",
      "thumbnail": "https://i.ytimg.com/vi/plN7JMbadRg/hq720_custom_1.jpg?sqp=CLzt-NYG-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLA6NGm14PT06lxEOnh0i1whckVo3Q",
      "channel": {
        "id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
        "title": "MrBeast",
        "handle": "MrBeast",
        "thumbnail": "https://yt3.ggpht.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJzXrnJiuDE=s68-c-k-c0x00ffffff-no-rj"
      },
      "viewCountText": "299,049,213 views",
      "viewCountInt": 299049213,
      "publishedTimeText": "3 weeks ago",
      "publishedTime": "2026-10-04T17:07:18.906Z",
      "lengthText": "57:59",
      "lengthSeconds": 3479,
      "badges": [
        "CC"
      ]
    }
  ],
  "channels": [
    {
      "type": "channel",
      "id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
      "channelName": "MrBeast",
      "handle": "MrBeast",
      "description": "SUBSCRIBE FOR A COOKIE! New MrBeast or MrBeast Gaming video every single Saturday at noon eastern time!",
      "thumbnail": "http://yt3.ggpht.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJzXrnJiuDE=s176-c-k-c0x00ffffff-no-rj-mo",
      "subscriberCountText": "523M",
      "subscriberCountInt": 523000000,
      "badges": [
        "Verified"
      ]
    },
    {
      "type": "channel",
      "id": "UCIPPMRA040LQr5QPyJEbmXA",
      "channelName": "MrBeast Gaming",
      "handle": "MrBeastGaming",
      "description": "New MrBeast or MrBeast Gaming video every single Saturday at noon eastern time! MrBeast Gaming - SUBSCRIBE OR ELSE.",
      "thumbnail": "http://yt3.googleusercontent.com/ytc/AIdro_lMiSL6eHqg2dVxvll6mVMeXo1qVak4TZ4_7mEWdobRRCk=s176-c-k-c0x00ffffff-no-rj-mo",
      "subscriberCountText": "60.9M",
      "subscriberCountInt": 60900000,
      "badges": [
        "Verified"
      ]
    }
  ],
  "playlists": [],
  "shorts": [
    {
      "type": "short",
      "id": "mND4T0lzg_g",
      "url": "https://www.youtube.com/watch?v=mND4T0lzg_g",
      "title": "How People Treat You Based on Subscribers",
      "viewCountText": "22M",
      "viewCountInt": 22000000
    },
    {
      "type": "short",
      "id": "Y8IJi7iP5vk",
      "url": "https://www.youtube.com/watch?v=Y8IJi7iP5vk",
      "title": "Last To Fall Wins",
      "viewCountText": "117M",
      "viewCountInt": 117000000
    }
  ],
  "shelves": [],
  "lives": [],
  "continuationToken": "ErwDEgdtcmJlYXN0GrADU0JTQ0FSaFZRMWcyVDFFelJHdGpjMkpaVGtVMlNEaDFVVkYxVmtHQ0FSaFZRMGxRVUUxU1FUQTBNRXhSY2pWUlVIbEtSV0p0V0VHQ0FRdHVUVEl4YUZaeGRtaHRhNElCQzNZNVVYUk5ObkZ1UnpVd2dnRUxibVJCVVdaVWVteFdhbU9DQVF0QlpqWnBOa05vUVZaVWQ0SUJDMWhxTUVwMGFtY3piRWhSZ2dFTFVYUnNPR3hLZDJKa05HZUNBUXRmWDJadFJHb3dXa294VVlJQkMwUllWa2h0UjI5RFZHTnZnZ0VMZWxKMFIwd3dMVFZ5WnpTQ0FRdHBXV3hQUkhScmVYZGZTWUlCQ3paYWVUVldUR05GWWxwamdnRUxT…"
}

Common to every endpoint

Any route can answer these: a missing or wrong key, no credits left, the platform not answering, or a failure on our side. None of them costs credits.

GET /v1/cosmos/profile?handle=design

{
  "success": false,
  "message": "Invalid API key"
}

04Notes

YouTube decides the page size (often 20–30 videos, plus channels and Shorts). The answer always has six lists (`videos`, `channels`, `playlists`, `shorts`, `shelves`, `lives`) plus `continuationToken`; lists that do not apply are empty. Pass `continuationToken` back for the next page; it is null on the last page, and a later page can repeat an item. Unknown `sortBy`, `type` and `duration` values are ignored. In a mixed search, Shorts are short entries (id, url, title, view count); with `type=shorts` they are full video items. A search with no results returns empty lists for 0 credits.

05Errors & credits

Every error has success: false, a real HTTP status and costs no credits.

400missing_parameter
A required parameter is missing or invalid.
403private_account
The account is private or age-restricted.
404not_found
No such account.
503upstream_error
The platform did not answer; retry shortly.