SocialCrawl Linkedin Ads API

openapi: 3.2.0
info:
  title: SocialCrawl Linkedin 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: linkedin-ads
  description: Linkedin-ads endpoints
paths:
  /linkedin/ad:
    get:
      summary: Get LinkedIn ad details
      description: Returns detailed information about a specific LinkedIn advertisement including ad copy, sponsor info, impressions, and targeting.
      tags:
      - linkedin-ads
      operationId: get_linkedin_ad
      security:
      - ApiKeyAuth: []
      x-credit-tier: advanced
      x-credit-cost: 5
      parameters:
      - name: url
        in: query
        required: true
        description: Full URL of the LinkedIn ad
        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 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
                          amazon_shop_trending_picks:
                            type:
                            - array
                            - 'null'
                            description: Array at post.ext.amazon_shop_trending_picks
                            items:
                              type: string
                              description: Leaf at post.ext.amazon_shop_trending_picks
                          amazon_shop_curations:
                            type:
                            - array
                            - 'null'
                            description: Array at post.ext.amazon_shop_curations
                            items:
                              type: string
                              description: Leaf at post.ext.amazon_shop_curations
                          amazon_shop_socials:
                            type:
                            - array
                            - 'null'
                            description: Array at post.ext.amazon_shop_socials
                            items:
                              type: string
                              description: String at post.ext.amazon_shop_socials
                          ad:
                            type:
                            - string
                            - 'null'
                            description: 'Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface.'
                          apple_music:
                            type:
                            - string
                            - 'null'
                            description: Leaf at post.ext.apple_music
                      _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'
  /linkedin/ads/search:
    get:
      summary: Search LinkedIn ads
      description: Searches the LinkedIn Ad Library for ads by company, keyword, or filters. Returns matching ads with ad copy and sponsor info.
      tags:
      - linkedin-ads
      operationId: get_linkedin_ads_search
      security:
      - ApiKeyAuth: []
      x-credit-tier: advanced
      x-credit-cost: 5
      parameters:
      - name: company
        in: query
        required: false
        description: The company name to search for. 'Microsoft' for example
        schema:
          type: string
      - name: keyword
        in: query
        required: false
        description: The keyword to search for
        schema:
          type: string
      - name: companyId
        in: query
        required: false
        description: The company id to search for
        schema:
          type: string
      - name: countries
        in: query
        required: false
        description: 'Comma separated list of countries. Example: US,CA,MX'
        schema:
          type: string
      - name: startDate
        in: qu

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