SocialCrawl Youtube API

openapi: 3.2.0
info:
  title: SocialCrawl Youtube API
  version: 1.0.0
  description: 'Unified social media data API - one API key, one consistent response format, 50 platforms, 400 endpoints. Power AI agents with clean social data.


    Slim variant: inline examples removed and the shared error responses hoisted into components. The full annotated spec is at https://www.socialcrawl.dev/openapi.json.'
  contact:
    name: SocialCrawl
    url: https://www.socialcrawl.dev
    email: support@socialcrawl.dev
servers:
- url: https://www.socialcrawl.dev/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: youtube
  description: Youtube endpoints
paths:
  /youtube/channel:
    get:
      summary: Get YouTube channel info
      description: Returns public channel information for a YouTube channel including subscriber count, total video count, total view count, channel description, banner URL, and avatar URL. `author.followers` is YouTube's publicly published subscriber figure. Above 1,000 subscribers YouTube rounds that figure to three significant figures, and `author.ext.followers_approximate` is true.
      tags:
      - youtube
      operationId: get_youtube_channel
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      x-socialcrawl-oneOf:
      - - channelId
        - handle
        - url
      parameters:
      - name: channelId
        in: query
        required: false
        description: 'YouTube channel ID. Can pass a channelId, handle or url (one of: channelId, handle, url; at least one required)'
        schema:
          type: string
      - name: handle
        in: query
        required: false
        description: 'YouTube channel handle without the @ symbol (one of: channelId, handle, url; at least one required)'
        schema:
          type: string
      - name: url
        in: query
        required: false
        description: 'YouTube channel URL. Can pass a channelId, handle or url (one of: channelId, handle, url; at least one required)'
        schema:
          type: string
      - name: hl
        in: query
        required: false
        description: Preferred response language for localized text (ISO 639-1, e.g. 'en', 'es', 'fr').
        schema:
          type: string
      - name: forUsername
        in: query
        required: false
        description: Legacy YouTube username (pre-handle) to look up.
        schema:
          type: string
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      id:
                        type: string
                        description: Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)
                      username:
                        type:
                        - string
                        - 'null'
                        description: User handle or username
                      display_name:
                        type:
                        - string
                        - 'null'
                        description: Display name or full name
                      avatar_url:
                        type:
                        - string
                        - 'null'
                        description: URL to profile picture
                      bio:
                        type:
                        - string
                        - 'null'
                        description: Profile biography or description
                      verified:
                        type:
                        - boolean
                        - 'null'
                        description: Whether the account is verified
                      followers:
                        type:
                        - integer
                        - 'null'
                        description: Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true.
                      following:
                        type:
                        - integer
                        - 'null'
                        description: Number of accounts followed
                      posts_count:
                        type:
                        - integer
                        - 'null'
                        description: Total number of posts / videos / tracks / episodes
                      likes_count:
                        type:
                        - integer
                        - 'null'
                        description: Total likes received across the author's content (when surfaced)
                      url:
                        type:
                        - string
                        - 'null'
                        description: Direct URL to the profile page
                      location:
                        type:
                        - string
                        - 'null'
                        description: ISO region code (e.g. `US`) or freeform location string when surfaced
                      external_url:
                        type:
                        - string
                        - 'null'
                        description: Bio link / external website URL when surfaced by the platform
                      private:
                        type:
                        - boolean
                        - 'null'
                        description: Boolean at author.private
                      joined_at:
                        type:
                        - string
                        - 'null'
                        description: String at author.joined_at
                      ext:
                        type:
                        - object
                        - 'null'
                        description: 'Nested object: author.ext'
                        properties:
                          social_context:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.social_context
                          account_created:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.account_created
                          country:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.country
                          former_usernames:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.former_usernames
                            items:
                              type: string
                              description: String at author.ext.former_usernames
                          public_email:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.public_email
                          public_phone:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.public_phone
                          business_category:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.business_category
                          hd_avatar_url:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.hd_avatar_url
                          website:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.website
                          cover_url:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.cover_url
                          page_active:
                            type:
                            - boolean
                            - 'null'
                            description: Boolean at author.ext.page_active
                          employee_count:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.employee_count
                          employee_count_range:
                            type:
                            - object
                            - 'null'
                            description: 'Nested object: author.ext.employee_count_range'
                            properties:
                              start:
                                type:
                                - integer
                                - 'null'
                                description: Numeric at author.ext.employee_count_range.start
                              end:
                                type:
                                - integer
                                - 'null'
                                description: Numeric at author.ext.employee_count_range.end
                          founded_year:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.founded_year
                          specialities:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.specialities
                            items:
                              type: string
                              description: String at author.ext.specialities
                          industries:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.industries
                            items:
                              type: string
                              description: String at author.ext.industries
                          headquarters:
                            type:
                            - string
                            - 'null'
                            description: Leaf at author.ext.headquarters
                          locations:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.locations
                            items:
                              type: string
                              description: Leaf at author.ext.locations
                          hashtags:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.hashtags
                            items:
                              type: string
                              description: Leaf at author.ext.hashtags
                          funding:
                            type:
                            - string
                            - 'null'
                            description: Leaf at author.ext.funding
                          address:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.address
                          price_range:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.price_range
                          rating:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.rating
                          rating_count:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.rating_count
                          talking_about_count:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.talking_about_count
                          business_hours:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.business_hours
                            items:
                              type: string
                              description: Leaf at author.ext.business_hours
                          links:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.links
                            items:
                              type: string
                              description: Leaf at author.ext.links
                          ad_library_page_id:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.ad_library_page_id
                          ad_library_status:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.ad_library_status
                          urn:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.urn
                          is_top_voice:
                            type:
                            - boolean
                            - 'null'
                            description: Boolean at author.ext.is_top_voice
                          is_premium:
                            type:
                            - boolean
                            - 'null'
                            description: Boolean at author.ext.is_premium
                          followers_approximate:
                            type:
                            - boolean
                            - 'null'
                            description: 'True when `author.followers` is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok `stats.followerCount` when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts.'
                          keywords:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.keywords
                          topicCategories:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.topicCategories
                            items:
                              type: string
                              description: String at author.ext.topicCategories
                          bannerExternalUrl:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.bannerExternalUrl
                          madeForKids:
                            type:
                            - boolean
                            - 'null'
                            description: Boolean at author.ext.madeForKids
                          hiddenSubscriberCount:
                            type:
                            - boolean
                            - 'null'
                            description: Boolean at author.ext.hiddenSubscriberCount
                          related_playlists:
                            type:
                            - string
                            - 'null'
                            description: Leaf at author.ext.related_playlists
                          topic_ids:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.topic_ids
                            items:
                              type: string
                              description: String at author.ext.topic_ids
                          unsubscribed_trailer:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.unsubscribed_trailer
                          monthly_listeners:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.monthly_listeners
                          total_ratings:
                            type:
                            - integer
                            - 'null'
                            description: 'Spotify podcasts only: how many listeners have rated the show. Cumulative over the show''s whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)'
                          average_rating:
                            type:
                            - integer
                            - 'null'
                            description: 'Spotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf'
                          creator_username:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.creator_username
                          join_policy:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.join_policy
                          is_nsfw:
                            type:
                            - boolean
                            - 'null'
                            description: Boolean at author.ext.is_nsfw
                          weekly_active_users:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.weekly_active_users
                          weekly_contributions:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.weekly_contributions
                          bio_link:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.bio_link
                          group:
                            type:
                            - string
                            - 'null'
                            description: Leaf at author.ext.group
                      _warnings:
                        type: array
                        description: 'Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as ''no warnings''.'
                        items:
                          type: string
                          description: One advisory notice.
                  credits_used:
                    type: integer
                    description: Number of credits consumed
                  credits_remaining:
                    type:
                    - integer
                    - 'null'
                    description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
                  request_id:
                    type: string
                    description: Unique request identifier for support
                  cached:
                    type: boolean
                    description: Whether the response was served from cache
                  idempotent_replay:
                    type: boolean
                    description: True only when this response is an idempotency replay
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
  /youtube/channel/videos:
    get:
      summary: List YouTube channel videos
      description: 'Returns a list of recent videos published by a YouTube channel. Each video includes title, view count, like count, comment count, duration, thumbnail URL, and publish date. SHORTS: this reads the channel''s Videos tab, which is long-form only. Shorts are a separate shelf on YouTube and never appear here (measured 0 of 30 items on 2 channels, 2026-08-11). For a channel''s Shorts call `/v1/youtube/channel/shorts` (1 credit, same `channelId`/`handle`); the two sets are disjoint, so calling both and concatenating gives the channel''s full catalogue for 2 credits. Every item on both endpoints carries `post.ext.content_type` (`video` or `short`) so the merged list stays separable.'
      tags:
      - youtube
      operationId: get_youtube_channel_videos
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      x-socialcrawl-oneOf:
      - - channelId
        - handle
      parameters:
      - name: channelId
        in: query
        required: false
        description: 'YouTube channel ID (one of: channelId, handle; at least one required)'
        schema:
          type: string
      - name: handle
        in: query
        required: false
        description: 'YouTube channel handle without the @ symbol (one of: channelId, handle; at least one required)'
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: Sort by latest or popular
        schema:
          type: string
          enum:
          - latest
          - popular
      - name: continuationToken
        in: query
        required: false
        description: 'Continuation token to get more videos. Get ''continuationToken'' from previous response. Native upstream cursor param. Send the universal `cursor` instead: the API maps it to this name for you.'
        deprecated: true
        schema:
          type: string
      - name: includeExtras
        in: query
        required: false
        description: Set to `true` to add the like count and comment count (`post.engagement.likes` / `.comments`) and the video description (`post.ext.description`). For the full per-video detail use /v1/youtube/video. Slows the response slightly.
        schema:
          type: string
      - name: is_paid_promotions
        in: query
        required: false
        description: 'Set to ''true'' to search YouTube''s public paid product placement / sponsorship / endorsement surface: returns normal videos where the creator disclosed a paid promotion.'
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        description: 'Universal pagination cursor. Send `pagination.next_cursor` from the previous response back verbatim: the API maps it to this endpoint''s native `continuationToken` (cursor style). You never construct, decode, or look up a cursor. Omit it for page 1.'
        schema:
          type: string
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      items:
                        type: array
                        description: Array of canonical post wrappers ({ post, computed })
                        items:
                          type: object
                          description: Canonical post wrapper
                          properties:
                            post:
                              type: object
                              description: Canonical Post object (unified across all platforms)
                              properties:
                                id:
                                  type: string
                                  description: Platform-specific post ID (always a string; numeric upstream IDs are stringified)
                                url:
                                  type:
                                  - string
                                  - 'null'
                                  description: Direct URL to the post on the source platform
                                content:
                                  type: object
                                  description: Post content fields (text, media, thumbnail, duration)
                                  properties:
                                    text:
                                      type:
                                      - string
                                      - 'null'
                                      description: Post caption, description, or text content
                                    media_urls:
                                      type:
                                      - string
                                      - array
                                      - 'null'
                                      description: URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.
                                      items:
                                        type: string
                                        description: URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.
                                    thumbnail_url:
                                      type:
                                      - string
                                      - 'null'
                                      description: URL to thumbnail image
                                    duration_seconds:
       

# --- truncated at 32 KB (754 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socialcrawl/refs/heads/main/openapi/socialcrawl-youtube-api-openapi.yml