---
title: "Search"
method: GET
path: "/v1/youtube/search"
tags: ["youtube"]
---

# Search

`GET /v1/youtube/search`

## Request

- Base URL: `https://api.insightsocial.app`
- URL: `https://api.insightsocial.app/v1/youtube/search`
- Auth: API key in header `x-api-key`

Returns YouTube search results for a keyword: videos, channels, playlists, shorts, and live streams, each with title, thumbnail, views, and channel.

Use it for a general keyword search across every content kind; search/advanced returns videos only but adds date, license, and country filters.

**Metered: 10–150 credits.** We reserve the ceiling when the call starts and charge what it actually used when it finishes.

Paginates by `cursor`: see [Pagination](https://www.insightsocial.app/docs/pagination).

## Query parameters

- `query` string, required
- `uploadDate` 'today' | 'this_week' | 'this_month' | 'this_year'
- `sortBy` 'relevance' | 'popular'
- `type` 'videos' | 'shorts' | 'channels' | 'playlists'
- `duration` 'under_3_min' | 'between_3_and_20_min' | 'over_20_min'
- `region` string
- `includeExtras` string
- `include` string
- `exact_dates` 'true' | 'false'
- `dry_run` '1'
- `since` string
- `until` string
- `min_views` integer
- `max_age_days` integer
- `sort_rows` 'views'
- `max_pages` integer
- `cursor` string

## Response `200`

Success.

- object
  - `success` true, required
  - `platform` string, required
  - `endpoint` string, required
  - `schema_version` '2', required
  - `data` PostPage, required
    - `items` object[], required
      - `post` Post, required
        - `id` string, required: An identifier, always a string. Never parse it as a number: several platforms use ids above 2^53.
        - `url` string, uri, nullable, required
        - `kind` string, nullable, required: The format of the post. Format words only, never a platform name. short = short-form vertical video (a reel, a TikTok, a YouTube Short).
        - `content` object, required
          - `text` string, nullable, required
          - `media_urls` string[], nullable, required
          - `thumbnail_url` string, uri, nullable, required
          - `duration_seconds` number, nullable, required
        - `author` Author, required
          - `id` string, nullable, required: An identifier, always a string. Never parse it as a number: several platforms use ids above 2^53.
          - `username` string, nullable, required
          - `display_name` string, nullable, required
          - `avatar_url` string, uri, nullable, required
          - `verified` boolean, nullable, required
        - `engagement` object, required
          - `views` integer, nullable, required: A count. null when the platform does not expose it; 0 only when it is really zero.
          - `likes` integer, nullable, required: A count. null when the platform does not expose it; 0 only when it is really zero.
          - `comments` integer, nullable, required: A count. null when the platform does not expose it; 0 only when it is really zero.
          - `shares` integer, nullable, required: A count. null when the platform does not expose it; 0 only when it is really zero.
          - `saves` integer, nullable, required: A count. null when the platform does not expose it; 0 only when it is really zero.
        - `flags` object, required
          - `nsfw` boolean, nullable, required
          - `spoiler` boolean, nullable, required
          - `pinned` boolean, nullable, required
          - `deleted` boolean, required
          - `likes_hidden` boolean, nullable, required
          - `comments_hidden` boolean, nullable, required
          - `shares_hidden` boolean, nullable, required
          - `views_hidden` boolean, nullable, required
          - `saves_hidden` boolean, nullable, required
        - `published_at` string, date-time, nullable, required: ISO-8601 timestamp in UTC, ending in Z.
        - `language` string, nullable, required: The content's language as the platform states it, e.g. en, pt-BR. Detected languages come later (§7.1).
        - `ext` object, nullable, required: Platform-specific fields, snake_case. The key list per platform is in the docs.
    - `total` integer, nullable, required: A count. null when the platform does not expose it; 0 only when it is really zero.
    - `truncated` boolean, nullable, required
    - `ext` object, nullable: Platform-specific fields, snake_case. The key list per platform is in the docs.
  - `pagination` Pagination
    - `next_cursor` string, nullable, required
    - `has_more` boolean, required
    - `page_size` integer, required
    - `stopped_at` 'since' | 'known_id' | 'end', nullable
  - `unavailable` string[], required
  - `credits_used` integer, required
  - `credits_remaining` integer, required
  - `request_id` string, required
  - `cached` boolean, required
  - `idempotent_replay` boolean, required
  - `charge_reason` string, required
  - `free_call` boolean, required

## Other responses

- `400`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `401`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `402`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `404`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `409`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `429`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `500`: See [Error handling](https://www.insightsocial.app/docs/errors).
- `503`: See [Error handling](https://www.insightsocial.app/docs/errors).

---

[API](https://skmtc.dev/insightsocial/apis/insightsocial-api.md) · [All operations](https://skmtc.dev/insightsocial/apis/insightsocial-api/llms.txt) · [OpenAPI document](https://skmtc.dev/insightsocial/apis/insightsocial-api/revisions/c82924cdabf2?raw)