SocialCrawl Tiktok Ads API

openapi: 3.2.0
info:
  title: SocialCrawl Tiktok Ads 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: tiktok-ads
  description: Tiktok-ads endpoints
paths:
  /tiktok/adlibrary/search:
    get:
      summary: Search the TikTok Ad Library
      description: Returns ads from the TikTok Ad Library matching a keyword or advertiser name. Each ad includes creative video, title, advertiser name, impression estimate, and first-shown date. Page with cursor.
      tags:
      - tiktok-ads
      operationId: get_tiktok_adlibrary_search
      security:
      - ApiKeyAuth: []
      x-credit-tier: advanced
      x-credit-cost: 5
      x-socialcrawl-oneOf:
      - - query
        - advertiser_name
      parameters:
      - name: query
        in: query
        required: false
        description: 'Keyword or phrase to search the TikTok Ad Library. (one of: query, advertiser_name; at least one required)'
        schema:
          type: string
      - name: advertiser_name
        in: query
        required: false
        description: 'Advertiser name as it appears in the TikTok Ad Library. (one of: query, advertiser_name; at least one required)'
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        description: Cursor from the previous response to fetch the next page.
        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:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Video/clip duration in seconds (null for non-video posts)
                                author:
                                  type: object
                                  description: Subset of Author fields for the post creator
                                  properties:
                                    username:
                                      type:
                                      - string
                                      - 'null'
                                      description: Author username
                                    display_name:
                                      type:
                                      - string
                                      - 'null'
                                      description: Author display name
                                    avatar_url:
                                      type:
                                      - string
                                      - 'null'
                                      description: URL to author profile picture
                                    verified:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Whether the author account is verified
                                engagement:
                                  type: object
                                  description: Engagement counts
                                  properties:
                                    views:
                                      type:
                                      - integer
                                      - 'null'
                                      description: 'View count (if available). For Instagram video/reels this is the play count: the headline ''Views'' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram''s play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`.'
                                    likes:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Like / reaction count
                                    comments:
                                      type:
                                      - integer
                                      - 'null'
                                      description: 'Comment count. Note: on `GET /v1/instagram/post` this is Instagram''s `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field.'
                                    shares:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated).
                                    saves:
                                      type:
                                      - integer
                                      - 'null'
                                      description: 'Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated).'
                                flags:
                                  type: object
                                  description: Boolean flags on the post
                                  properties:
                                    nsfw:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: NSFW flag (null when platform does not surface)
                                    spoiler:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Spoiler flag (null when platform does not surface)
                                    pinned:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Pinned-to-profile flag (null when platform does not surface)
                                    deleted:
                                      type: boolean
                                      description: Whether the post is tombstoned (always present)
                                    likes_hidden:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts.
                                    comments_hidden:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts.
                                    shares_hidden:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Boolean at post.flags.shares_hidden
                                    views_hidden:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Boolean at post.flags.views_hidden
                                    saves_hidden:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Boolean at post.flags.saves_hidden
                                published_at:
                                  type:
                                  - string
                                  - integer
                                  - 'null'
                                  description: Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle.
                                ext:
                                  type:
                                  - object
                                  - 'null'
                                  description: Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)
                                  properties:
                                    music_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: 'TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound'
                                    author_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `search/reels` items it is present on every row from every serving source, accepted by `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle.
                                    author_followers:
                                      type:
                                      - integer
                                      - 'null'
                                      description: 'The creator''s follower count as embedded in the search payload itself, when the search source happens to carry one. Historical on Instagram `search/reels`: Instagram stripped the follower count out of the search payload in August 2026, so it is now null on every Instagram row and no source can restore it. For a follower count call `/v1/instagram/profile?handle=` (1 credit, the exact current integer), or batch up to 50 creators through `POST /v1/prism/profiles`.'
                                    subreddit:
                                      type:
                                      - string
                                      - 'null'
                                      description: 'Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`'
                                    title:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.title
                                    selftext:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.selftext
                                    type:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.type
                                    content_type:
                                      type:
                                      - string
                                      - 'null'
                                      description: Leaf at post.ext.content_type
                                    ticker_symbols:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at post.ext.ticker_symbols
                                      items:
                                        type: string
                                        description: String at post.ext.ticker_symbols
                                    video_view_count:
                                      type:
                                      - integer
                                      - 'null'
                                      description: 'Instagram''s legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead.'
                                    ig_play_count:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts.
                                    published_at_epoch:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form.
                                    usertags:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at post.ext.usertags
                                      items:
                                        type: string
                                        description: Leaf at post.ext.usertags
                                    coauthors:
                                      type:
                                      - array
                                      - 'null'
                                      description: Instagram collaborative posts (the native "Collab" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).
                                      items:
                                        type: string
                                        description: Instagram collaborative posts (the native "Collab" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).
                                    music:
                                      type:
                                      - string
                                      - 'null'
                                      description: Leaf at post.ext.music
                                    sponsor_tags:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at post.ext.sponsor_tags
                                      items:
                                        type: string
                                        description: Leaf at post.ext.sponsor_tags
                                    location:
                                      type:
                                      - string
                                      - 'null'
                                      description: Leaf at post.ext.location
                                    reaction_counts:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at post.ext.reaction_counts
                                      items:
                                        type: string
                                        description: Leaf at post.ext.reaction_counts
                                    share_urn:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.share_urn
                                    post_type:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.post_type
                                    download_media_urls:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at post.ext.download_media_urls
                                      items:
                                        type: string
                                        description: Leaf at post.ext.download_media_urls
                                    tags:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at post.ext.tags
                                      items:
                                        type: string
                                        description: String at post.ext.tags
                                    categoryId:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.categoryId
                                    categoryTitle:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.categoryTitle
                                    topicCategories:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at post.ext.topicCategories
                                      items:
                                        type: string
                                        description: String at post.ext.topicCategories
                                    duration:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.duration
                                    license:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.license
                                    madeForKids:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Boolean at post.ext.madeForKids
                                    defaultAudioLanguage:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.defaultAudioLanguage
                                    hasPaidProductPlacement:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Boolean at post.ext.hasPaidProductPlacement
                                    caption:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.caption
                                    position:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at post.ext.position
                                    playlistId:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.playlistId
                                    videoOwnerChannelId:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.videoOwnerChannelId
                                    videoPublishedAt:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.videoPublishedAt
                                    description:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.description
                                    default_language:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.default_language
                                    playlist_item_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.playlist_item_id
                                    playlist_owner_channel_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.playlist_owner_channel_id
                                    playlist_owner_title:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.playlist_owner_title
                                    channel_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.channel_id
                                    video_count:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at post.ext.video_count
                                    commerce:
                                      type:
                                      - string
                                      - 'null'
                                      description: Leaf at post.ext.commerce
                                    on_screen_texts:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at post.ext.on_screen_texts
                                      items:
                                        type: string
                                        description: String at post.ext.on_screen_texts
                                    topic_tag:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.topic_tag
                                    topic_tag_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at post.ext.topic_tag_id
                                    amazon_shop_lists:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at post.ext.amazon_shop_lists
                                      items:
                                        type: string
                                        description: Leaf at post.ext.amazon_shop_lists
      

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