Search

Immutable Catalog Entry

This descriptor comes from the active versioned Portal catalog.

READscrape-creators.scrape_creators_youtube_get_v1_youtube_search

• Contract tier: legacy
• Risk: read
• Catalog version: scrape-creators-2026.07.12.1
• Descriptor hash: 3a031362a72ab9bd1706363a66cc1fc2b778aedb5147d05e4fe6980840181386

Use this when you need ScrapeCreators YouTube data from GET /v1/youtube/search for Search. Searches YouTube by keyword query and returns matching videos, channels, playlists, shorts, shelves, and live streams. Each video result includes title, URL, thumbnail, view count (views), publish date, duration, channel info, and badges. Supports filtering by upload date, sorting by relevance or popularity, and paginating with continuationToken. Set is_paid_promotions=true to search YouTube videos with the paid product placement / sponsorship disclosure. Returns the ScrapeCreators response in the standard MCP envelope with ok/data/error/meta. This is read-only. Requires the portal grant header and a ScrapeCreators BYOK API key.

Request Body

{
  "jsonrpc": "2.0",
  "id": "scrape-creators-scrape-creators-youtube-get-v1-youtube-search-example",
  "method": "tools/call",
  "params": {
    "name": "scrape-creators.scrape_creators_youtube_get_v1_youtube_search",
    "arguments": {
      "body": "",
      "type": "videos",
      "query": "",
      "params": "",
      "region": "",
      "sortBy": "relevance",
      "compact": "",
      "duration": "under_3_min",
      "max_items": "",
      "uploadDate": "today"
    }
  }
}

Arguments Schema

{
  "type": "object",
  "properties": {
    "body": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "null"
        }
      ],
      "title": "Body",
      "default": null,
      "description": "JSON request body for provider endpoints that accept one."
    },
    "type": {
      "enum": [
        "videos",
        "shorts",
        "channels",
        "playlists"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Type",
      "default": null,
      "description": "Type of content to search for"
    },
    "query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Query",
      "default": null,
      "description": "Search query"
    },
    "params": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ],
      "title": "Params",
      "default": null,
      "description": "Optional advanced query parameter object. Prefer the documented top-level parameters when available."
    },
    "region": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Region",
      "default": null,
      "description": "2 letter country code of the country to put the proxy in."
    },
    "sortBy": {
      "enum": [
        "relevance",
        "popular"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sortby",
      "default": null,
      "description": "Sort by"
    },
    "compact": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Compact",
      "default": null,
      "description": "When true, trims large list payloads before returning them to the agent."
    },
    "duration": {
      "enum": [
        "under_3_min",
        "between_3_and_20_min",
        "over_20_min"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Duration",
      "default": null,
      "description": "Duration of the video. Only applies to videos (not shorts)."
    },
    "max_items": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Max Items",
      "default": null,
      "description": "Maximum number of list items to return when compacting provider responses."
    },
    "uploadDate": {
      "enum": [
        "today",
        "this_week",
        "this_month",
        "this_year"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Uploaddate",
      "default": null,
      "description": "Upload date"
    },
    "include_raw": {
      "type": "boolean",
      "title": "Include Raw",
      "default": false,
      "description": "When true, returns both compact normalized data and the raw provider payload; this can be large."
    },
    "path_params": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ],
      "title": "Path Params",
      "default": null,
      "description": "Path template values for endpoints that expose path placeholders."
    },
    "search_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Search Query",
      "default": null,
      "description": "Alias for query: Search query"
    },
    "includeExtras": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Includeextras",
      "default": null,
      "description": "This will get you the like + comment count and the description. To get the full details of the video, use the /v1/youtube/video endpoint. *This will slow down the response slightly.*"
    },
    "cache_ttl_seconds": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cache Ttl Seconds",
      "default": null,
      "description": "Optional cache lifetime for idempotent GET requests."
    },
    "confirm_high_cost": {
      "type": "boolean",
      "title": "Confirm High Cost",
      "default": false,
      "description": "Set true only when intentionally running a high-credit or write-intent request."
    },
    "continuationToken": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Continuationtoken",
      "default": null,
      "description": "Continuation token to get more videos. Get 'continuationToken' from previous response."
    }
  },
  "additionalProperties": false
}

Output Schema

{
  "type": "object",
  "required": [
    "ok",
    "data",
    "error",
    "meta"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Whether the local or provider operation completed successfully."
    },
    "data": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "Bounded operation result when ok is true."
    },
    "meta": {
      "type": "object",
      "description": "Safe request, pagination, cache, and timing metadata.",
      "additionalProperties": true
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ],
      "description": "Safe structured error when ok is false."
    }
  },
  "description": "Scrape Creators MCP normalized response envelope.",
  "additionalProperties": false
}

Code Examples

cURL

curl -X POST 'https://portal.madpanda3d.com/api/mcp' \
  -H 'Authorization: Bearer mad_live_***' \
  -H 'Content-Type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": "scrape-creators-scrape-creators-youtube-get-v1-youtube-search-example",
  "method": "tools/call",
  "params": {
    "name": "scrape-creators.scrape_creators_youtube_get_v1_youtube_search",
    "arguments": {
      "body": "",
      "type": "videos",
      "query": "",
      "params": "",
      "region": "",
      "sortBy": "relevance",
      "compact": "",
      "duration": "under_3_min",
      "max_items": "",
      "uploadDate": "today"
    }
  }
}'

Node.js

const response = await fetch('https://portal.madpanda3d.com/api/mcp', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mad_live_***',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "jsonrpc": "2.0",
  "id": "scrape-creators-scrape-creators-youtube-get-v1-youtube-search-example",
  "method": "tools/call",
  "params": {
    "name": "scrape-creators.scrape_creators_youtube_get_v1_youtube_search",
    "arguments": {
      "body": "",
      "type": "videos",
      "query": "",
      "params": "",
      "region": "",
      "sortBy": "relevance",
      "compact": "",
      "duration": "under_3_min",
      "max_items": "",
      "uploadDate": "today"
    }
  }
}),
});
const data = await response.json();
console.log(data);

Python

import requests

url = 'https://portal.madpanda3d.com/api/mcp'
headers = {
    'Authorization': 'Bearer mad_live_***',
    'Content-Type': 'application/json',
}
payload = {
  "jsonrpc": "2.0",
  "id": "scrape-creators-scrape-creators-youtube-get-v1-youtube-search-example",
  "method": "tools/call",
  "params": {
    "name": "scrape-creators.scrape_creators_youtube_get_v1_youtube_search",
    "arguments": {
      "body": "",
      "type": "videos",
      "query": "",
      "params": "",
      "region": "",
      "sortBy": "relevance",
      "compact": "",
      "duration": "under_3_min",
      "max_items": "",
      "uploadDate": "today"
    }
  }
}
response = requests.post(url, headers=headers, json=payload, timeout=60)
print(response.json())

Example Responses

200 Success

{
  "ok": true,
  "message": "Tool scrape-creators.scrape_creators_youtube_get_v1_youtube_search executed successfully.",
  "note": "Response shape varies by MCP tool. Inspect live responses for exact fields."
}

502 Upstream Error

{
  "ok": false,
  "classification": "upstream_http_error",
  "message": "Upstream MCP returned a non-success status."
}