Ad details

Try in Playground

Retrieve a public ad by exact ID or canonical URL. Includes creative media, payer, advertiser, disclosed targeting, dates and impressions. Image, video, carousel, messages, InMail, article and event creatives have dedicated extraction; native documents expose their previews, and other formats are reported with partial coverage.

GET/v1/linkedin/adx-api-key

Headers

Get your API key

x-api-keystringrequiredheader

Your ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.

Query parameters

urlstringquery

Public HTTPS linkedin.com/ad-library/detail/ID URL.

max 4096 chars

adIdstringquery

Exact numeric ad ID as a string. Supply adId or url.

Example1234567890123456789

Response fields

idstring

Always included.

urlstring

Public HTTPS linkedin.com/ad-library/detail/ID URL.

absolute HTTPS URL

descriptionstringnullable

Always included.

headlinestringnullable

Always included.

posterstringnullable

Always included.

posterTitlestringnullable

Always included.

promotedBystringnullable

Always included.

paidForBystringnullable

Published payer, distinct from promoted-by attribution.

targetingobject

Source targeting text, preserving whitespace and hidden-control text for compatibility.

targetingDetailsobject

Cleaned language/location disclosure and all published inclusion/exclusion flags.

imagestringnullable

Always included.

videostringnullable

Always included.

Every published organic MP4 rendition in source order, with bitrate when present. video and organicVideo use the first rendition for reference compatibility.

up to 30 items

videoSources.urlstring

Always included.

videoSources.bitratenumbernullable

Always included.

carouselImagesstring[]

Always included.

creativeTypestringnullable

Always included.

thumbnailstringnullable

Always included.

preRollVideostringnullable

Published pre-roll MP4 when source metadata exposes it. Pre-roll attribution remains incomplete and this format reports partial coverage.

organicVideostringnullable

Always included.

preRollAdvertiserstringnullable

Always included.

sponsoredMessageSenderstringnullable

Always included.

sponsoredMessageSenderAvatarstringnullable

Always included.

sponsoredMessageTextstringnullable

Complete message text including list items; description retains the reference paragraph projection.

Native document cover images, title, manifest URL, preview page count and full count when published. Limited previews report partial coverage.

document.titlestringnullable

Always included.

document.previewPageCountinteger

Always included.

≥ 0

document.totalPageCountintegernullable

Always included.

document.coverImageUrlsstring[]

Always included.

up to 100 items

document.manifestUrlstringnullable

Always included.

Published message button text and type; destination URL stays null when the public source does not expose it.

sponsoredMessageButtons.textstring

Always included.

sponsoredMessageButtons.typestringnullable

Always included.

sponsoredMessageButtons.urlstringnullable

Always included.

landingPagestringnullable

Always included.

adTypestringnullable

Always included.

advertiserstringnullable

Always included.

advertiserLinkedinPagestringnullable

Always included.

advertiserLogostringnullable

Always included.

ctastringnullable

Always included.

destinationUrlstringnullable

Always included.

adDurationstringnullable

Published duration label; empty string when absent. Parsed dates remain null when unavailable.

startDatestringnullable

Real YYYY-MM-DD calendar date; requires endDate.

endDatestringnullable

Real YYYY-MM-DD date on or after startDate. LinkedIn applies its retained-ad date window.

totalImpressionsstringnullable

Original range label, never converted to a fabricated exact count.

All published countries, including those hidden by Show more.

impressionsByCountry.countrystring

Always included.

impressionsByCountry.impressionsstring

Always included.

requestIdstring

Random request correlation ID.

Attempts, decoded successful HTML bytes and elapsed time. Browser limits also count discarded responses.

accounting.upstreamRequestsinteger

Always included.

≥ 0

accounting.responseBytesinteger

Always included.

≥ 0

accounting.durationMsnumber

Always included.

≥ 0

successboolean

Whether usable public data was retrieved.

statusenum

success, partial, failed or challenged.

one of: success, partial

sourceUrlstring

Fixed-origin public source URL.

absolute HTTPS URL

fetchedAtstring

UTC retrieval timestamp.

Complete refers to this bounded page and supported creative fields, not all search results.

coverage.sourcestring

Always included.

coverage.completeboolean

Always included.

coverage.warningsstring[]

Always included.

Canonical Post at data.post for /ad; raw enriched items with next_cursor for /ads/search; normalized ad/ads and page metadata for /ad-library/ routes.

Always included.

data.post.idstring

Always included.

data.post.urlstring

Always included.

data.post.content.textstringnullable

Always included.

data.post.content.media_urlsstring | string[]

Always included.

data.post.content.thumbnail_urlstringnullable

Always included.

data.post.content.duration_secondsnullnullable

Always included.

data.post.author.usernamestringnullable

Always included.

data.post.author.display_namestringnullable

Always included.

data.post.author.avatar_urlstringnullable

Always included.

data.post.author.verifiednullnullable

Always included.

data.post.engagement.viewsnumbernullable

Always included.

data.post.engagement.likesnullnullable

Always included.

data.post.engagement.commentsnullnullable

Always included.

data.post.engagement.sharesnullnullable

Always included.

data.post.engagement.savesnullnullable

Always included.

data.post.flags.nsfwnullnullable

Always included.

data.post.flags.spoilernullnullable

Always included.

data.post.flags.pinnednullnullable

Always included.

data.post.flags.deletedboolean

Always included.

data.post.published_atstringnullable

Always included.

HTTP 200 returns the success variant. Check status: partial means usable data with warnings, and failed or challenged requests carry a failure object described in Errors & responses.

Error codes

HTTP	failure.code	Meaning
400	`invalid_request`	Invalid, duplicate, unknown or conflicting inputs.
401	`unauthorized`	Missing or incorrect service key.
403	`restricted_page`	The source restricts this ad.
404	`not_found`	Missing ad or route.
429	`upstream_rate_limited`	Source throttling.
502	`upstream_challenged` `unsupported_page`	Challenge, unsupported markup or identity mismatch.
502	`upstream_error` `unsafe_redirect` `response_too_large` `payload_too_complex` `request_limit`	Bounded source failure.
503	`busy`	Worker capacity reached.
504	`timeout`	Request deadline elapsed.
200	`partial`	Unavailable details, other creative formats or additional variants.

Code example

curl "https://api.scrapeatlas.com/v1/linkedin/ad?adId=1234567890123456789" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.scrapeatlas.com/v1/linkedin/ad?adId=1234567890123456789",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY"
    }
  }
);

const data = await response.json();
console.log(data.status, data);

type Result = {
  status: "success" | "partial" | "failed" | "challenged";
  requestId: string;
  [field: string]: unknown;
};

const response = await fetch(
  "https://api.scrapeatlas.com/v1/linkedin/ad?adId=1234567890123456789",
  {
    headers: {
      "x-api-key": process.env.SCRAPEATLAS_API_KEY!
    }
  }
);

const data = (await response.json()) as Result;
if (data.status === "failed" || data.status === "challenged") {
  throw new Error(`LinkedIn Ads Library request failed: ${data.requestId}`);
}
console.log(data);

import requests

response = requests.get(
    "https://api.scrapeatlas.com/v1/linkedin/ad",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "adId": "1234567890123456789"
    },
    timeout=60,
)
data = response.json()
print(data["status"], data)

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.scrapeatlas.com/v1/linkedin/ad?adId=1234567890123456789", nil)
	req.Header.Set("x-api-key", "YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
	fmt.Println(data["status"], data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();
        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.scrapeatlas.com/v1/linkedin/ad?adId=1234567890123456789"))
            .GET()
            .header("x-api-key", "YOUR_API_KEY")
            .build();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Use your sa_live_… customer key at https://api.scrapeatlas.com.

Responses

Successful result. Synthetic example validated against the runtime contract.

{
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "sourceUrl": "https://www.linkedin.com/ad-library/detail/1234567890123456789",
  "fetchedAt": "2026-09-11T00:00:00.000Z",
  "coverage": {
    "source": "public_page",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 30000,
    "durationMs": 1200
  },
  "id": "1234567890123456789",
  "url": "https://www.linkedin.com/ad-library/detail/1234567890123456789",
  "description": "Synthetic ad copy.",
  "headline": "A synthetic campaign",
  "poster": "Example",
  "posterTitle": "Promoted",
  "promotedBy": null,
  "paidForBy": "Example",
  "targeting": {
    "language": "Targeting includes English"
  },
  "image": "https://media.licdn.com/example.png",
  "video": null,
  "carouselImages": [],
  "creativeType": "SPONSORED_STATUS_UPDATE",
  "thumbnail": "https://media.licdn.com/example.png",
  "preRollVideo": null,
  "organicVideo": null,
  "preRollAdvertiser": null,
  "sponsoredMessageSender": null,
  "sponsoredMessageSenderAvatar": null,
  "sponsoredMessageButtons": [],
  "landingPage": "https://example.com",
  "adType": "Single Image Ad",
  "advertiser": "Example",
  "advertiserLinkedinPage": "https://www.linkedin.com/company/123",
  "advertiserLogo": null,
  "cta": "Learn more",
  "destinationUrl": "https://example.com",
  "adDuration": "Ran from Aug 1, 2026 to Aug 31, 2026",
  "startDate": "2026-08-01T00:00:00.000Z",
  "endDate": "2026-08-31T00:00:00.000Z",
  "totalImpressions": "5k-10k",
  "impressionsByCountry": [
    {
      "country": "Germany",
      "impressions": "100%"
    }
  ],
  "data": {
    "post": {
      "id": "1234567890123456789",
      "url": "https://www.linkedin.com/ad-library/detail/1234567890123456789",
      "content": {
        "text": "Synthetic ad copy.",
        "media_urls": "https://media.licdn.com/example.png",
        "thumbnail_url": "https://media.licdn.com/example.png",
        "duration_seconds": null
      },
      "author": {
        "username": "Example",
        "display_name": "Example",
        "avatar_url": null,
        "verified": null
      },
      "engagement": {
        "views": null,
        "likes": null,
        "comments": null,
        "shares": null,
        "saves": null
      },
      "flags": {
        "nsfw": null,
        "spoiler": null,
        "pinned": null,
        "deleted": false
      },
      "published_at": "2026-08-01T00:00:00.000Z"
    }
  },
  "targetingDetails": {
    "language": "Targeting includes English"
  },
  "sponsoredMessageText": null,
  "document": null,
  "videoSources": []
}

Invalid, duplicate, unknown or conflicting inputs.

{
  "requestId": "9d2f1c0a-6b1e-4c7d-9a8e-2f3b4c5d6e7f",
  "accounting": {
    "upstreamRequests": 0,
    "responseBytes": 0,
    "durationMs": 0
  },
  "success": false,
  "status": "failed",
  "failure": {
    "code": "invalid_request",
    "message": "Invalid request: missing, duplicate, unsupported or malformed parameters."
  }
}