> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). The sections below mirror the orientation block in [`/llms.txt`](https://www.socialfetch.dev/llms.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need a structured operation inventory. The catalog covers documented operations with on-site reference pages. ## This page - **On-site (HTML):** [https://www.socialfetch.dev/docs/api/v1/youtube/search/get](https://www.socialfetch.dev/docs/api/v1/youtube/search/get) - **Markdown (.mdx) URL:** [https://www.socialfetch.dev/docs/api/v1/youtube/search/get.mdx](https://www.socialfetch.dev/docs/api/v1/youtube/search/get.mdx) ## API base URL and authentication - **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev` - **Authentication:** send `x-api-key: sfk_...` on `/v1/**` routes unless the operation is explicitly anonymous (check OpenAPI `security`, the [API reference hub](https://www.socialfetch.dev/docs/api.mdx), [`/llms.txt`](https://www.socialfetch.dev/llms.txt), or [`/llms.json`](https://www.socialfetch.dev/llms.json) for each route). - **OpenAPI JSON:** [https://www.socialfetch.dev/openapi.json](https://www.socialfetch.dev/openapi.json) ## Recommended docs entrypoints (this site) - [Documentation overview](https://www.socialfetch.dev/docs.mdx) — top-level orientation (markdown). - [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx) — authenticate with `x-api-key`, validate auth with `whoami`, and understand the JSON envelope. - [SDK](https://www.socialfetch.dev/docs/sdk.mdx) — official TypeScript SDK guide, including `SocialFetchClient`, `Result`, and `unwrap()`. - [SDK reference](https://www.socialfetch.dev/docs/sdk-reference.mdx) — exhaustive SDK method inventory and route mapping for agents, tooling, and power users. - [Choose the right endpoint](https://www.socialfetch.dev/docs/choose-endpoint.mdx) — task-oriented route selection for smoke tests, profiles, list endpoints, and single-item lookups. - [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — fast comparison of identifiers, pagination, outcomes, media download, and SDK coverage. - [`/llms.json`](https://www.socialfetch.dev/llms.json) — structured machine-readable operation inventory with parameter names, pagination, outcomes, credits, and SDK mapping. - [API reference hub](https://www.socialfetch.dev/docs/api.mdx) — human-friendly index of operations with links into generated pages. - [Errors](https://www.socialfetch.dev/docs/errors.mdx) — shared error envelope and HTTP status guidance. - [Credits](https://www.socialfetch.dev/docs/credits.mdx) — metering, `402`, and planning batch jobs. - Outcome semantics such as `found`, `not_found`, and `private` are documented in [Errors](https://www.socialfetch.dev/docs/errors.mdx) and on operation pages when present in the OpenAPI contract. ## Markdown docs convention - Every docs page has a markdown twin: append **`.mdx`** to the docs pathname (for example `/docs/quickstart` → `/docs/quickstart.mdx`). - Agents that send `Accept: text/markdown` on `/docs/**` HTML URLs may receive markdown directly (same URL, `Vary: Accept`). --- # Search YouTube (https://www.socialfetch.dev/docs/api/v1/youtube/search/get) ## Summary Search YouTube. **Tags:** `YouTube` ## HTTP - **Method:** GET - **Path:** `/v1/youtube/search` - **Base URL:** `https://api.socialfetch.dev` ## Capability summary - **SDK mapping:** `client.youtube.search({ query, uploadDate?, sortBy?, type?, duration?, region?, cursor?, includeExtras? })` - **Pagination:** cursor via `cursor`, next cursor: `data.page.nextCursor`, has more: `data.page.hasMore` - **Ordering / list behavior:** Supported sort options: relevance, popular. ## Authentication - **`x-api-key`**: API key (`sfk_...`) ## Parameters ### `query` (query) - **Required:** yes - **Constraints:** type `string`; minLength: 1; maxLength: 512 - **Description:** Search query text for YouTube content. ### `uploadDate` (query) - **Required:** no - **Constraints:** type `string`; enum: today, this_week, this_month, this_year - **Description:** Optional upload date filter for video results. ### `sortBy` (query) - **Required:** no - **Constraints:** type `string`; enum: relevance, popular - **Description:** Optional sort order for search results. ### `type` (query) - **Required:** no - **Constraints:** type `string`; enum: videos, shorts, channels, playlists - **Description:** Optional content type filter for search results. ### `duration` (query) - **Required:** no - **Constraints:** type `string`; enum: under_3_min, between_3_and_20_min, over_20_min - **Description:** Optional duration filter for video results. Applies to videos, not shorts. ### `region` (query) - **Required:** no - **Constraints:** type `string`; minLength: 2; maxLength: 2 - **Description:** Optional two-letter region code for localized search results. ### `cursor` (query) - **Required:** no - **Constraints:** type `string`; minLength: 1 - **Description:** Opaque pagination cursor returned by a previous response. ### `includeExtras` (query) - **Required:** no - **Constraints:** type `boolean` - **Description:** When true, returns richer per-video metadata when available. May increase response time. ## Behavior notes - **`sortBy`**: Optional sort order for search results. - **`region`**: Optional two-letter region code for localized search results. ## Pagination This endpoint uses **cursor-based pagination** via the `cursor` query parameter. - Read **hasMore** from `data.page.hasMore`. - When that value is `true`, read **nextCursor** from `data.page.nextCursor` and pass it as the `cursor` query parameter on the **next** request (URL-encode when building a query string). - Omit `cursor` on the **first** request. - Stop when **hasMore** is `false` or **nextCursor** is null (end of list). ## Responses (status codes) - **200**: Search results for the requested query. - **400**: Invalid query parameters - **401**: Missing or invalid API key - **402**: Insufficient credits - **500**: Unexpected or billing error - **502**: Lookup could not be completed from the response (unexpected or invalid data). - **503**: Service temporarily unavailable; safe to retry with backoff. ## Response body (200) Search results for the requested query. ### Field outline - **data** (required) — type `object`. Endpoint-specific response payload. - **query** (required) — type `string`. Search query string evaluated for this response. - **videos** (required) — type `array`. Matching YouTube videos. - _items:_ - **id** (required) — type `string`; minLength: 1. YouTube content identifier. - **kind** (required) — type `string`; enum: video, short, live. Normalized media kind for this row. - **url** (required) — type `string`; nullable. Canonical public URL for this item when available. - **title** (required) — type `string`; nullable. Title shown for this item. - **thumbnailUrl** (required) — type `string`; nullable. Thumbnail image URL when available. - **channel** (required) — type `object`; nullable. Channel metadata when available. - **id** (required) — type `string`; nullable. Channel identifier when available. - **title** (required) — type `string`; nullable. Channel title when available. - **handle** (required) — type `string`; nullable. Channel handle when available. - **thumbnailUrl** (required) — type `string`; nullable. Channel thumbnail URL when available. - **viewCount** (required) — type `integer`; minimum: 0; nullable. View count when available. - **viewCountText** (required) — type `string`; nullable. Human-readable view count label when available. - **publishedAt** (required) — type `string`; nullable. ISO-8601 publish timestamp when available. May be null for some live items. - **publishedTimeText** (required) — type `string`; nullable. Human-readable relative publish time when available. - **durationSeconds** (required) — type `integer`; minimum: 0; nullable. Duration in seconds when available. - **durationText** (required) — type `string`; nullable. Human-readable duration label when available. - **badges** (required) — type `array`. Display badges such as New, Live, or 4K when present. - _items:_ - type `string` - **description** (optional) — type `string`; nullable. Description text when extras are requested and available. - **likeCount** (optional) — type `integer`; minimum: 0; nullable. Like count when extras are requested and available. - **likeCountText** (optional) — type `string`; nullable. Human-readable like count when extras are requested. - **commentCount** (optional) — type `integer`; minimum: 0; nullable. Comment count when extras are requested and available. - **commentCountText** (optional) — type `string`; nullable. Human-readable comment count when extras are requested. - **shorts** (required) — type `array`. Matching YouTube Shorts. - _items:_ - **id** (required) — type `string`; minLength: 1. YouTube content identifier. - **kind** (required) — type `string`; enum: video, short, live. Normalized media kind for this row. - **url** (required) — type `string`; nullable. Canonical public URL for this item when available. - **title** (required) — type `string`; nullable. Title shown for this item. - **thumbnailUrl** (required) — type `string`; nullable. Thumbnail image URL when available. - **channel** (required) — type `object`; nullable. Channel metadata when available. - **id** (required) — type `string`; nullable. Channel identifier when available. - **title** (required) — type `string`; nullable. Channel title when available. - **handle** (required) — type `string`; nullable. Channel handle when available. - **thumbnailUrl** (required) — type `string`; nullable. Channel thumbnail URL when available. - **viewCount** (required) — type `integer`; minimum: 0; nullable. View count when available. - **viewCountText** (required) — type `string`; nullable. Human-readable view count label when available. - **publishedAt** (required) — type `string`; nullable. ISO-8601 publish timestamp when available. May be null for some live items. - **publishedTimeText** (required) — type `string`; nullable. Human-readable relative publish time when available. - **durationSeconds** (required) — type `integer`; minimum: 0; nullable. Duration in seconds when available. - **durationText** (required) — type `string`; nullable. Human-readable duration label when available. - **badges** (required) — type `array`. Display badges such as New, Live, or 4K when present. - _items:_ - type `string` - **description** (optional) — type `string`; nullable. Description text when extras are requested and available. - **likeCount** (optional) — type `integer`; minimum: 0; nullable. Like count when extras are requested and available. - **likeCountText** (optional) — type `string`; nullable. Human-readable like count when extras are requested. - **commentCount** (optional) — type `integer`; minimum: 0; nullable. Comment count when extras are requested and available. - **commentCountText** (optional) — type `string`; nullable. Human-readable comment count when extras are requested. - **channels** (required) — type `array`. Matching YouTube channels. - _items:_ - **id** (required) — type `string`; minLength: 1. YouTube channel identifier. - **name** (required) — type `string`; nullable. Channel display name. - **handle** (required) — type `string`; nullable. Channel handle when available. - **description** (required) — type `string`; nullable. Channel description snippet when available. - **thumbnailUrl** (required) — type `string`; nullable. Channel avatar or banner thumbnail when available. - **subscriberCount** (required) — type `integer`; minimum: 0; nullable. Subscriber count when available. - **subscriberCountText** (required) — type `string`; nullable. Human-readable subscriber count when available. - **badges** (required) — type `array`. Display badges such as Verified when present. - _items:_ - type `string` - **playlists** (required) — type `array`. Matching YouTube playlists. - _items:_ - **id** (required) — type `string`; minLength: 1. YouTube playlist identifier. - **title** (required) — type `string`; nullable. Playlist title. - **url** (required) — type `string`; nullable. Canonical playlist URL when available. - **thumbnailUrl** (required) — type `string`; nullable. Playlist thumbnail URL when available. - **videoCount** (required) — type `integer`; minimum: 0; nullable. Number of videos in the playlist when available. - **videoId** (required) — type `string`; nullable. Representative video id shown for the playlist when available. - **videoUrl** (required) — type `string`; nullable. Representative video URL when available. - **channel** (required) — type `object`; nullable. Playlist owner channel when available. - **id** (required) — type `string`; nullable. Playlist owner channel id when available. - **title** (required) — type `string`; nullable. Playlist owner channel title. - **handle** (required) — type `string`; nullable. Playlist owner handle when available. - **url** (required) — type `string`; nullable. Playlist owner channel URL when available. - **shelves** (required) — type `array`. Grouped shelf rows when returned. - _items:_ - **type** (required) — type `string`; nullable. Shelf type label when available. - **title** (required) — type `string`; nullable. Shelf title when available. - **items** (required) — type `array`. Media items grouped in this shelf. - _items:_ - **id** (required) — type `string`; minLength: 1. YouTube content identifier. - **kind** (required) — type `string`; enum: video, short, live. Normalized media kind for this row. - **url** (required) — type `string`; nullable. Canonical public URL for this item when available. - **title** (required) — type `string`; nullable. Title shown for this item. - **thumbnailUrl** (required) — type `string`; nullable. Thumbnail image URL when available. - **channel** (required) — type `object`; nullable. Channel metadata when available. - **viewCount** (required) — type `integer`; minimum: 0; nullable. View count when available. - **viewCountText** (required) — type `string`; nullable. Human-readable view count label when available. - **publishedAt** (required) — type `string`; nullable. ISO-8601 publish timestamp when available. May be null for some live items. - **publishedTimeText** (required) — type `string`; nullable. Human-readable relative publish time when available. - **durationSeconds** (required) — type `integer`; minimum: 0; nullable. Duration in seconds when available. - **durationText** (required) — type `string`; nullable. Human-readable duration label when available. - **badges** (required) — type `array`. Display badges such as New, Live, or 4K when present. - _items:_ - type `string` - **description** (optional) — type `string`; nullable. Description text when extras are requested and available. - **likeCount** (optional) — type `integer`; minimum: 0; nullable. Like count when extras are requested and available. - **likeCountText** (optional) — type `string`; nullable. Human-readable like count when extras are requested. - **commentCount** (optional) — type `integer`; minimum: 0; nullable. Comment count when extras are requested and available. - **commentCountText** (optional) — type `string`; nullable. Human-readable comment count when extras are requested. - **liveStreams** (required) — type `array`. Matching YouTube live streams. - _items:_ - **id** (required) — type `string`; minLength: 1. YouTube content identifier. - **kind** (required) — type `string`; enum: video, short, live. Normalized media kind for this row. - **url** (required) — type `string`; nullable. Canonical public URL for this item when available. - **title** (required) — type `string`; nullable. Title shown for this item. - **thumbnailUrl** (required) — type `string`; nullable. Thumbnail image URL when available. - **channel** (required) — type `object`; nullable. Channel metadata when available. - **id** (required) — type `string`; nullable. Channel identifier when available. - **title** (required) — type `string`; nullable. Channel title when available. - **handle** (required) — type `string`; nullable. Channel handle when available. - **thumbnailUrl** (required) — type `string`; nullable. Channel thumbnail URL when available. - **viewCount** (required) — type `integer`; minimum: 0; nullable. View count when available. - **viewCountText** (required) — type `string`; nullable. Human-readable view count label when available. - **publishedAt** (required) — type `string`; nullable. ISO-8601 publish timestamp when available. May be null for some live items. - **publishedTimeText** (required) — type `string`; nullable. Human-readable relative publish time when available. - **durationSeconds** (required) — type `integer`; minimum: 0; nullable. Duration in seconds when available. - **durationText** (required) — type `string`; nullable. Human-readable duration label when available. - **badges** (required) — type `array`. Display badges such as New, Live, or 4K when present. - _items:_ - type `string` - **description** (optional) — type `string`; nullable. Description text when extras are requested and available. - **likeCount** (optional) — type `integer`; minimum: 0; nullable. Like count when extras are requested and available. - **likeCountText** (optional) — type `string`; nullable. Human-readable like count when extras are requested. - **commentCount** (optional) — type `integer`; minimum: 0; nullable. Comment count when extras are requested and available. - **commentCountText** (optional) — type `string`; nullable. Human-readable comment count when extras are requested. - **totalResults** (required) — type `integer`; minimum: 0. Count of top-level result rows returned in this response across all buckets. - **page** (required) — type `object`. Pagination information for the current response. - **nextCursor** (required) — type `string`; nullable. Cursor to pass in the next request when another page exists. - **hasMore** (required) — type `boolean`. Whether another page of results is available. - **meta** (required) — type `object`. Metadata describing the request and billing outcome. - **requestId** (required) — type `string`; minLength: 1. Unique request identifier for tracing this API call. - **creditsCharged** (required) — type `integer`; minimum: 0. Credits charged for this request. - **version** (required) — type `string`; enum: v1. Public API version that served the response. ### Example JSON (results) ```json { "data": { "query": "running", "videos": [ { "id": "yln9Wd9TgS8", "kind": "video", "url": "https://www.youtube.com/watch?v=yln9Wd9TgS8", "title": "I’ve Been Running for 7 Years - Here’s What Actually Made Me Faster!", "thumbnailUrl": "https://i.ytimg.com/vi/yln9Wd9TgS8/hq720.jpg?sqp=-oaymwEXCNAFEJQDSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLCzOITVi6O_puFCAtr2Oa8km72ueA", "channel": { "id": "UC-vlZFFRyWKx-d3LpoAhNfg", "title": "Ben Is Running", "handle": "BenIsRunning", "thumbnailUrl": "https://yt3.ggpht.com/K-mVXkTijLVtW2pVByXP5FuW026wV6bVesxWI8AJfgABAYYpylZqRxp-sfyWEwSBbwMTgpYE=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 46871, "viewCountText": "46,871 views", "publishedAt": "2026-05-18T04:47:52.217Z", "publishedTimeText": "1 day ago", "durationSeconds": 890, "durationText": "14:50", "badges": [ "New", "4K" ] }, { "id": "hM0qOmKZP0g", "kind": "video", "url": "https://www.youtube.com/watch?v=hM0qOmKZP0g", "title": "Kameron Marlowe - Running (Official Music Video)", "thumbnailUrl": "https://i.ytimg.com/vi/hM0qOmKZP0g/hq720.jpg?sqp=-oaymwEXCNAFEJQDSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLAnWIc3OL-WKnTpJY1WBMiT2vCDEQ", "channel": { "id": "UCWSqMNoaslymTKNYC4I8Fqg", "title": "Kameron Marlowe", "handle": "channel/UCWSqMNoaslymTKNYC4I8Fqg", "thumbnailUrl": "https://yt3.ggpht.com/aJHXUqJwMKk7AE3_zV4IFcwSQXX7chyk8iFfl0fFtOLw0qcokVK1EDNo5LC8u-OgV3DAi5EPGWQ=s88-c-k-c0x00ffffff-no-rj" }, "viewCount": 357279, "viewCountText": "357,279 views", "publishedAt": "2026-05-08T04:47:52.217Z", "publishedTimeText": "11 days ago", "durationSeconds": 160, "durationText": "2:40", "badges": [ "4K" ] }, { "id": "_bowCTqEp34", "kind": "video", "url": "https://www.youtube.com/watch?v=_bowCTqEp34", "title": "I Ran Every Day for 30 Days, This is What it Did to My Body", "thumbnailUrl": "https://i.ytimg.com/vi/_bowCTqEp34/hq720.jpg?sqp=-oaymwEXCNAFEJQDSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLBudmCXts7TKOPyNCOavVtLKy5iTw", "channel": { "id": "UCEjIjshJ8bvvCkGNk0pkYcA", "title": "Jesse James West", "handle": "JesseJamesWest", "thumbnailUrl": "https://yt3.ggpht.com/ytc/AIdro_kk2Qpy2IZ4iXFV7i0pJaNN7l8m3lYReyFGu-z60UPityOp=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 9959530, "viewCountText": "9,959,530 views", "publishedAt": "2025-05-19T04:47:52.217Z", "publishedTimeText": "1 year ago", "durationSeconds": 1646, "durationText": "27:26", "badges": [ "4K" ] }, { "id": "YlLWQvzhGVQ", "kind": "video", "url": "https://www.youtube.com/watch?v=YlLWQvzhGVQ", "title": "The Psychology Of People Who Love Running", "thumbnailUrl": "https://i.ytimg.com/vi/YlLWQvzhGVQ/hq720.jpg?sqp=-oaymwEXCNAFEJQDSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLAi09Jhe_Owd3zvlGhW9-5SKbc_ow", "channel": { "id": "UCESCdB5zKn5KAb8dG2Q2zdw", "title": "Nicklas Rossner", "handle": "NicklasRossnerPT", "thumbnailUrl": "https://yt3.ggpht.com/_rHUDggAueTG55Tn04E2Z-F33Ml4FQshqU2rABmPmHgdDCJtLyHqStFCqWgWPBRXsoaQszkT=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 279415, "viewCountText": "279,415 views", "publishedAt": "2026-02-19T04:47:52.217Z", "publishedTimeText": "3 months ago", "durationSeconds": 856, "durationText": "14:16", "badges": [ "4K" ] }, { "id": "1Y8aRXArpgM", "kind": "video", "url": "https://www.youtube.com/watch?v=1Y8aRXArpgM", "title": "how running for a YEAR changed my life & body | +20 beginner tips, essentials, fuelling & mindset", "thumbnailUrl": "https://i.ytimg.com/vi/1Y8aRXArpgM/hq720.jpg?sqp=-oaymwEXCNAFEJQDSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLBZx2YS1c07sKY956vlKWSPhzi0HA", "channel": { "id": "UCpEcZL5B7i6gJYGfqLvMCbg", "title": "Linda Sun", "handle": "lindasunyt", "thumbnailUrl": "https://yt3.ggpht.com/ytc/AIdro_mB6pKvGojQrwfeWx80o4pXgOwQIVDyfLVF5J64HL06KA=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 1316969, "viewCountText": "1,316,969 views", "publishedAt": "2025-05-19T04:47:52.217Z", "publishedTimeText": "1 year ago", "durationSeconds": 1471, "durationText": "24:31", "badges": [] }, { "id": "0J42_MuTxoU", "kind": "video", "url": "https://www.youtube.com/watch?v=0J42_MuTxoU", "title": "How Running Completely Changes The Human Body", "thumbnailUrl": "https://i.ytimg.com/vi/0J42_MuTxoU/hq720.jpg?sqp=-oaymwEXCNAFEJQDSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLBE9jhPnGIj-3AeJoYK-Axov-knzg", "channel": { "id": "UCESCdB5zKn5KAb8dG2Q2zdw", "title": "Nicklas Rossner", "handle": "NicklasRossnerPT", "thumbnailUrl": "https://yt3.ggpht.com/_rHUDggAueTG55Tn04E2Z-F33Ml4FQshqU2rABmPmHgdDCJtLyHqStFCqWgWPBRXsoaQszkT=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 1563458, "viewCountText": "1,563,458 views", "publishedAt": "2025-09-19T04:47:52.217Z", "publishedTimeText": "8 months ago", "durationSeconds": 454, "durationText": "7:34", "badges": [ "4K" ] }, { "id": "H7ga2jhlaus", "kind": "video", "url": "https://www.youtube.com/watch?v=H7ga2jhlaus", "title": "How Running Rewires Your Brain and Transforms Your Body", "thumbnailUrl": "https://i.ytimg.com/vi/H7ga2jhlaus/hq720.jpg?sqp=-oaymwEXCNAFEJQDSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLDr5nXCT3akiTpfATwUQWAoL5rfmQ", "channel": { "id": "UCGQAS6kKc7jpeYj7OKHLoNA", "title": "Jay Freddy ⚕️", "handle": "JayFriedrichs", "thumbnailUrl": "https://yt3.ggpht.com/znqLBw57bPFhzwyLXR0junF8mlwv4pgF2AFiJl9foevdgVLasXiNpU8CsRH8SoiUk9GQJfX0-g=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 1043724, "viewCountText": "1,043,724 views", "publishedAt": "2025-05-19T04:47:52.217Z", "publishedTimeText": "1 year ago", "durationSeconds": 1377, "durationText": "22:57", "badges": [] }, { "id": "XzYXnLqgS2I", "kind": "video", "url": "https://www.youtube.com/watch?v=XzYXnLqgS2I", "title": "The Most Comfortable Running Shoes for Every Type of Run", "thumbnailUrl": "https://i.ytimg.com/vi/XzYXnLqgS2I/hq720_custom_2.jpg?sqp=CMzVr9AG-oaymwEXCNAFEJQDSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLCxwyrq0502S5Jpty_9PYLaavw2cg", "channel": { "id": "UCZPqG0yh_xPm2AyLjffbDvw", "title": "Ben Parkes", "handle": "BenParkes", "thumbnailUrl": "https://yt3.ggpht.com/ytc/AIdro_mDy4ZoQqcj7DiO_-1z6j2Y6Nu_PvFESGAsJagEM5FdPg=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 54023, "viewCountText": "54,023 views", "publishedAt": "2026-05-18T04:47:52.217Z", "publishedTimeText": "1 day ago", "durationSeconds": 1267, "durationText": "21:07", "badges": [ "New", "4K" ] }, { "id": "CrTJR-SHfsI", "kind": "video", "url": "https://www.youtube.com/watch?v=CrTJR-SHfsI", "title": "Information Society - Running", "thumbnailUrl": "https://i.ytimg.com/vi/CrTJR-SHfsI/hq720.jpg?sqp=-oaymwEXCNAFEJQDSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLCWKX4ueAb4mR_QYE6SDxEMbSuLig", "channel": { "id": "UCnSR7_Oq-MdsZxfogsfk-Ug", "title": "Tommy Boy", "handle": "TommyBoyRecords", "thumbnailUrl": "https://yt3.ggpht.com/hoVaJvLBxH5TndCUo--3swrnT-tYkS4gv8EgVae4eCMm_c3oxHTEXbIyCMj0A0B7hDFvT28tCA=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 11690560, "viewCountText": "11,690,560 views", "publishedAt": "2019-05-19T04:47:52.217Z", "publishedTimeText": "7 years ago", "durationSeconds": 467, "durationText": "7:47", "badges": [ "CC" ] } ], "shorts": [], "channels": [], "playlists": [], "shelves": [], "liveStreams": [], "totalResults": 9, "page": { "nextCursor": "Es8BEgdydW5uaW5nGsABU0JTQ0FRdDViRzQ1VjJRNVZHZFRPSUlCQzJoTk1IRlBiVXRhVURCbmdnRUxYMkp2ZDBOVWNVVndNelNDQVF0WmJFeFhVWFo2YUVkV1VZSUJDekZaT0dGU1dFRnljR2ROZ2dFTE1FbzBNbDlOZFZSNGIxV0NBUXRJTjJkaE1tcG9iR0YxYzRJQkMxaDZXVmh1VEhGblV6SkpnZ0VMUTNKVVNsSXRVMGhtYzBteUFRWUtCQWdORUFMcUFRUUlBaEFaoAIEGIHg6BgiC3NlYXJjaC1mZWVk", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } ``` ### Example JSON (empty) ```json { "data": { "query": "zzzzzzzzzzzzzzzzzzzz_no_match_99999", "videos": [], "shorts": [], "channels": [], "playlists": [], "shelves": [], "liveStreams": [], "totalResults": 0, "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_empty", "creditsCharged": 1, "version": "v1" } } ``` ### Example JSON (paginated) ```json { "data": { "query": "running", "videos": [ { "id": "BzSzwqb-OEE", "kind": "video", "url": "https://www.youtube.com/watch?v=BzSzwqb-OEE", "title": "NF - RUNNING (Audio)", "thumbnailUrl": "https://i.ytimg.com/vi/BzSzwqb-OEE/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLCasEKav1CLqeSSE2IYDqjGiIMBGw", "channel": { "id": "UCoRR6OLuIZ2-5VxtnQIaN2w", "title": "NFrealmusic", "handle": "channel/UCoRR6OLuIZ2-5VxtnQIaN2w", "thumbnailUrl": "https://yt3.ggpht.com/fn5hgnPgI7SS8przRsemtRr-ITzvevKWerxkk9soKwgiK5jcCN0hh2mHiWgmcjUK-Bqo6K2-BUA=s88-c-k-c0x00ffffff-no-rj" }, "viewCount": 19870726, "viewCountText": "19,870,726 views", "publishedAt": "2023-05-19T04:48:25.413Z", "publishedTimeText": "3 years ago", "durationSeconds": 254, "durationText": "4:14", "badges": [] }, { "id": "6l0Qp1GXY7w", "kind": "video", "url": "https://www.youtube.com/watch?v=6l0Qp1GXY7w", "title": "NF - RUNNING (Lyrics)", "thumbnailUrl": "https://i.ytimg.com/vi/6l0Qp1GXY7w/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLBWYszI_N1ezpehAw-Tv7BZDz5j8Q", "channel": { "id": "UCcJZ-w0N3-Z2jnJ8UgoBclQ", "title": "SauceOnly", "handle": "SauceOnly", "thumbnailUrl": "https://yt3.ggpht.com/dy5MPezFhnDfpaf7loqoSTGAS9LuIo4EOs-ckW9FMGU15KlG7SFtvzFNVEcfH8DCBpHs8Hxe=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 2589761, "viewCountText": "2,589,761 views", "publishedAt": "2023-05-19T04:48:25.413Z", "publishedTimeText": "3 years ago", "durationSeconds": 254, "durationText": "4:14", "badges": [] }, { "id": "aAg3bwzSuLk", "kind": "video", "url": "https://www.youtube.com/watch?v=aAg3bwzSuLk", "title": "DIGITAL CIRCUS - “The One Who's Running the Show” [Official Music Video]", "thumbnailUrl": "https://i.ytimg.com/vi/aAg3bwzSuLk/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLAUeH44XdDW7pnGU7OLXd6cdxR7OA", "channel": { "id": "UCn_FAXem2-e3HQvmK-mOH4g", "title": "GLITCH", "handle": "GLITCH", "thumbnailUrl": "https://yt3.ggpht.com/JgzaWBB7n02Ru2TTmcVLCJJNBW1mLnh_f6eJYPOuEShb3PaXmwkqas5zfpA_sVXjYkg_UNmx=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 29537030, "viewCountText": "29,537,030 views", "publishedAt": "2026-04-19T04:48:25.413Z", "publishedTimeText": "1 month ago", "durationSeconds": 152, "durationText": "2:32", "badges": [ "CC" ] }, { "id": "LX-61VykjDc", "kind": "video", "url": "https://www.youtube.com/watch?v=LX-61VykjDc", "title": "BEGINNER RUNNER TO INTERMEDIATE… A Simple Guide To Run Faster & Longer!", "thumbnailUrl": "https://i.ytimg.com/vi/LX-61VykjDc/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLCAiBSLjBgVrsId5dl2_NNtzjj-wQ", "channel": { "id": "UCZPqG0yh_xPm2AyLjffbDvw", "title": "Ben Parkes", "handle": "BenParkes", "thumbnailUrl": "https://yt3.ggpht.com/ytc/AIdro_mDy4ZoQqcj7DiO_-1z6j2Y6Nu_PvFESGAsJagEM5FdPg=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 108469, "viewCountText": "108,469 views", "publishedAt": "2026-03-19T04:48:25.413Z", "publishedTimeText": "2 months ago", "durationSeconds": 858, "durationText": "14:18", "badges": [ "4K" ] }, { "id": "9aLWNixqiMU", "kind": "video", "url": "https://www.youtube.com/watch?v=9aLWNixqiMU", "title": "I Doubled My Run Every Day For 18 Days", "thumbnailUrl": "https://i.ytimg.com/vi/9aLWNixqiMU/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLD8ZBQimVYfzAp-ipUq4yjaTgT4vA", "channel": { "id": "UCaFUrR3oSxOl5Y9y6tvLTEg", "title": "WillNE", "handle": "WillNE", "thumbnailUrl": "https://yt3.ggpht.com/jHP9KlhlAzuL53nEquudGPcHi7_WDQoBxlkIihP7xGtgRau_XQUfoyWuZAavrIZrHZyAl2m5=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 2927119, "viewCountText": "2,927,119 views", "publishedAt": "2025-05-19T04:48:25.413Z", "publishedTimeText": "1 year ago", "durationSeconds": 1596, "durationText": "26:36", "badges": [ "4K" ] }, { "id": "GwKnceMTw9Y", "kind": "video", "url": "https://www.youtube.com/watch?v=GwKnceMTw9Y", "title": "Ultimate Beginner's Guide to Running", "thumbnailUrl": "https://i.ytimg.com/vi/GwKnceMTw9Y/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLBIKc5qWwPNLypF5JY3pP2xGbaoFA", "channel": { "id": "UCv9ingiPmqKs6ejZV2Pt6Dw", "title": "Shervin Shares", "handle": "ShervinShares", "thumbnailUrl": "https://yt3.ggpht.com/3mDFiUgmrGjz5jjP1JKGldbTxxpG-DM8Na86a2SsLdyFsSQphpfbSNMg40XNuteiQdRmDhJlUw=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 659234, "viewCountText": "659,234 views", "publishedAt": "2025-05-19T04:48:25.413Z", "publishedTimeText": "1 year ago", "durationSeconds": 1457, "durationText": "24:17", "badges": [ "4K", "CC" ] }, { "id": "3H2l9Lo-jPk", "kind": "video", "url": "https://www.youtube.com/watch?v=3H2l9Lo-jPk", "title": "No Doubt - Running (Official Music Video)", "thumbnailUrl": "https://i.ytimg.com/vi/3H2l9Lo-jPk/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLDe5XI_n3MmO56ZxbvpADl8Np8n2Q", "channel": { "id": "UCtJXMyhnbdIQrCSDwAeJlNw", "title": "No Doubt", "handle": "channel/UCtJXMyhnbdIQrCSDwAeJlNw", "thumbnailUrl": "https://yt3.ggpht.com/zpk6mVs_6BzgIGyFVt_skpYAI-KKTzI88xb5C7nZ4iAR2HABNeOGcR_6qQaQtNtHOLqM_gT9Yg=s88-c-k-c0x00ffffff-no-rj" }, "viewCount": 10478691, "viewCountText": "10,478,691 views", "publishedAt": "2010-05-19T04:48:25.413Z", "publishedTimeText": "16 years ago", "durationSeconds": 238, "durationText": "3:58", "badges": [ "CC" ] }, { "id": "uzRi7FS6iAY", "kind": "video", "url": "https://www.youtube.com/watch?v=uzRi7FS6iAY", "title": "How To Run Faster For Longer", "thumbnailUrl": "https://i.ytimg.com/vi/uzRi7FS6iAY/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLBWcGiQUwgpvj5UPLr6I0BgiVmkfw", "channel": { "id": "UCbVEx9qG_hLrb6FrWQJz_Tg", "title": "Nick Bare", "handle": "nickbarefitness", "thumbnailUrl": "https://yt3.ggpht.com/ytc/AIdro_mVx6fQ8UNrMx2sjhQ5JwJyQTCfSXAoznqRdRSZLoxmGqQ=s68-c-k-c0x00ffffff-no-rj" }, "viewCount": 1923133, "viewCountText": "1,923,133 views", "publishedAt": "2024-05-19T04:48:25.413Z", "publishedTimeText": "2 years ago", "durationSeconds": 718, "durationText": "11:58", "badges": [ "4K" ] } ], "shorts": [], "channels": [ { "id": "UCnI3TuOg8D3SCRPW8ET4EAg", "name": "Total Running Productions", "handle": "TotalRunningProductions", "description": "Running documentaries, athlete analysis, behind the scenes. All for the love of the run.", "thumbnailUrl": "http://yt3.googleusercontent.com/ytc/AIdro_lDT5Wr19q7bcLT8tC2lDwL9LEEQJH48ixg6_QTT8wSMVI=s176-c-k-c0x00ffffff-no-rj-mo", "subscriberCount": 802000, "subscriberCountText": "802K", "badges": [ "Verified" ] } ], "playlists": [], "shelves": [], "liveStreams": [], "totalResults": 9, "page": { "nextCursor": "EvMBEgdydW5uaW5nGuQBU0NpQ0FRdENlbE42ZDNGaUxVOUZSWUlCQ3pac01GRndNVWRZV1RkM2dnRUxZVUZuTTJKM2VsTjFUR3VDQVF0TVdDMDJNVlo1YTJwRVk0SUJDemxoVEZkT2FYaHhhVTFWZ2dFTE1rcFJielp2TWs1S1ZUU0NBUXRIZDB0dVkyVk5WSGM1V1lJQkdGVkRia2t6VkhWUFp6aEVNMU5EVWxCWE9FVlVORVZCWjRJQkN6TklNbXc1VEc4dGFsQnJnZ0VMZFhwU2FUZEdVelpwUVZteUFRWUtCQWdaRUFQcUFRUUlCQkF5oAIEGIHg6BgiC3NlYXJjaC1mZWVk", "hasMore": true } }, "meta": { "requestId": "req_01example_page_2", "creditsCharged": 1, "version": "v1" } } ``` ### Machine-readable error codes When an error JSON body is returned, it may include one of these `error.code` values (derived from the OpenAPI schemas for this operation; additional codes may exist at runtime): - `bad_request` ## Error handling & retries Interpret HTTP status codes using the descriptions below. Do not assume a JSON body unless the OpenAPI schema defines one for that status. - **400**: Invalid query parameters **Retry:** Fix the request; retrying the same invalid payload will not help. - **401**: Missing or invalid API key **Retry:** Fix the API key first; retrying without changes will not help. - **402**: Insufficient credits **Retry:** Do not retry without resolving billing/credits (retrying the same request will not help). - **500**: Unexpected or billing error - **502**: Lookup could not be completed from the response (unexpected or invalid data). **Retry:** May be transient; a few retries with backoff are reasonable. - **503**: Service temporarily unavailable; safe to retry with backoff. **Retry:** Usually safe to retry with exponential backoff and jitter. ### Suggested client defaults - Send the API key using the `x-api-key` header on every request. - On `503` (and sometimes `502`), retry with backoff; cap retries and surface a clear error to the user. - On `402`, surface an actionable billing message rather than blind retries. ## Examples ### TypeScript SDK ```typescript import { SocialFetchClient } from "@socialfetch/sdk"; const client = new SocialFetchClient({ apiKey: process.env.SOCIALFETCH_API_KEY!, }); const result = await client.youtube.search({ query: "value", }); if (!result.ok) { console.error(result.error); } else { console.log(result.value.data); } ``` ### Node.js ```javascript const response = await fetch( "https://api.socialfetch.dev/v1/youtube/search?query=value", { headers: { "x-api-key": "YOUR_API_KEY", } } ); const data = await response.json(); console.log(data); ``` ### cURL ```bash curl "https://api.socialfetch.dev/v1/youtube/search?query=value" \ -H "x-api-key: YOUR_API_KEY" ``` ### Python ```python import requests response = requests.get( "https://api.socialfetch.dev/v1/youtube/search?query=value", headers={"x-api-key": "YOUR_API_KEY"}, ) data = response.json() print(data) ``` ### Example: optional query parameters First request illustrating common optional query flags (adjust values to your integration): ```javascript const url = "https://api.socialfetch.dev/v1/youtube/search?sortBy=relevance"; const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const data = await response.json(); ``` ### Example: next page (pagination) After a successful response, if pagination is not finished, request the next page using `cursor` (URL-encode when composing the query string): ```javascript const previous = await response.json(); const nextCursor = previous?.data?.page?.nextCursor; const hasMore = previous?.data?.page?.hasMore; if (!hasMore || nextCursor == null) { // no more pages } else { const nextUrl = new URL("https://api.socialfetch.dev/v1/youtube/search"); nextUrl.searchParams.set("cursor", nextCursor); // optionally preserve sort: nextUrl.searchParams.set("sortBy", "latest"); const nextResponse = await fetch(nextUrl.toString(), { headers: { "x-api-key": "YOUR_API_KEY" }, }); const nextData = await nextResponse.json(); } ```