POST /linkedin_ad_details • Credits: 2 credits per call

LinkedIn Ad Details returns the full detail of one LinkedIn ad. Send a POST request with the LinkedIn Ad Library detail URL of the ad. The response holds the ad ID, the ad format, the advertiser, every creative variant, the targeting criteria and the impression counts. Each call costs 2 credits.

What does LinkedIn Ad Details do?

The LinkedIn Ad Library shows the ads that a company runs, but a search result carries only a headline and a thumbnail. LinkedIn Ad Details closes that gap. The endpoint reads the public Ad Library detail page for the ad URL that you send. It returns the ad as structured JSON in one synchronous response. The data source is the LinkedIn Ad Library. One call covers one ad.

Marketing teams use LinkedIn Ad Details for competitive intelligence. The response names the paying entity, the creative format and the call-to-action label. It also carries the full ad copy of every variant, the countries that saw the ad and the audience segments that the advertiser targeted.

Which endpoint does LinkedIn Ad Details use?

Method: POST
URL: https://api.richapi.ai/api/v1/linkedin_ad_details
Authentication: x-api-key header
Response: Synchronous JSON
Credits: 2 credits per call

CAUTION: LinkedIn Ad Details accepts POST only. A GET request returns status 405 with the message linkedin_ad_details only supports POST. Put the ad_url parameter in the request body, never in the query string.

How to send a LinkedIn Ad Details request

Copy your API key from the RichAPI dashboard.
Open the ad in the LinkedIn Ad Library.
Copy the detail URL from the address bar. The URL ends with the numeric ad ID.
Set the ad_url parameter to that detail URL.
Send a POST request to https://api.richapi.ai/api/v1/linkedin_ad_details.
Send the API key in the x-api-key header.
Read the ad fields from the element object in the response.

CAUTION: Each LinkedIn Ad Details call costs 2 credits. One call covers one ad.

cURL

curl -X POST https://api.richapi.ai/api/v1/linkedin_ad_details   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "ad_url": "https://www.linkedin.com/ad-library/detail/1215501393"
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/linkedin_ad_details",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"ad_url": "https://www.linkedin.com/ad-library/detail/1215501393"},
    timeout=60,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/linkedin_ad_details", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ad_url: "https://www.linkedin.com/ad-library/detail/1215501393",
  }),
});

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

What parameters does LinkedIn Ad Details accept?

Parameter	Type	Required	Default	Description
`ad_url`	string	Yes	`""`	The LinkedIn Ad Library detail URL of the ad, for example `https://www.linkedin.com/ad-library/detail/1215501393`.

LinkedIn Ad Details takes one parameter. The dashboard, the MCP tool and the automation editor show the same parameter under the label Ad URL.

CAUTION: The request body key is ad_url. A request body that uses the key url returns status 400 with the message Unknown input field(s): url.

Which ad identifier does LinkedIn Ad Details accept?

LinkedIn Ad Details accepts one ad identifier format: the public LinkedIn Ad Library detail URL. The numeric ad ID is the last segment of that URL. In https://www.linkedin.com/ad-library/detail/1215501393, the ad ID is 1215501393.

Identifier that you hold	What to do
LinkedIn Ad Library detail URL	Send it as the `ad_url` parameter.
Numeric LinkedIn ad ID	Add the ID to `https://www.linkedin.com/ad-library/detail/`, then send the result as the `ad_url` parameter.
Advertiser name or a keyword only	Send LinkedIn Ad Search first, then read the `content.pageUrl` field of each result.

How to research the LinkedIn ads of a competitor

LinkedIn Ad Search returns a page of ads for an advertiser, a keyword or a country. Each search result carries an id field and a content.pageUrl field. LinkedIn Ad Details turns one such pageUrl into the full ad, with the targeting and the impression counts that the search result omits. The two endpoints pair as a two-step flow: search wide, then fetch the detail of the interesting ads only.

Send a POST request to https://api.richapi.ai/api/v1/linkedin_ad_search with the account_owner parameter set to the competitor name.
Read the elements array from the search response.
Pick the ads that match your criteria.
Send one POST request to https://api.richapi.ai/api/v1/linkedin_ad_details for each picked ad.
Set the ad_url parameter to the content.pageUrl field of the search result.
Read element.about, element.variants, element.targeting and element.impressions from each detail response.

import requests

BASE_URL = "https://api.richapi.ai/api/v1"
HEADERS = {"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"}

# Step 1: find the ads that one advertiser runs. One page returns up to 24 ads.
search = requests.post(
    f"{BASE_URL}/linkedin_ad_search",
    headers=HEADERS,
    json={
        "account_owner": "UX Pilot AI",
        "countries": "US",
        "date_option": "last-30-days",
    },
    timeout=60,
)
search.raise_for_status()
ads = search.json().get("elements", [])

# Step 2: fetch the full detail of the first 10 ads.
for ad in ads[:10]:
    ad_url = (ad.get("content") or {}).get("pageUrl")
    if not ad_url:
        continue
    detail = requests.post(
        f"{BASE_URL}/linkedin_ad_details",
        headers=HEADERS,
        json={"ad_url": ad_url},
        timeout=60,
    )
    detail.raise_for_status()
    element = detail.json().get("element")
    if element is None:
        continue
    about = element.get("about") or {}
    variants = element.get("variants") or []
    print(about.get("advertiserName"), about.get("format"), len(variants))

What does the two-step LinkedIn ad flow cost?

LinkedIn Ad Search costs 0.2 credits per ad returned, and one page returns up to 24 ads. LinkedIn Ad Details costs 2 credits per call. The example above reads one search page of 24 ads and fetches the detail of 10 ads. The table uses $0.02 a credit, the rate on the 1,000 and 5,000 credit packs.

Step	Calls	Credits	Cost
LinkedIn Ad Search, one page of 24 ads	1	4.8	$0.096
LinkedIn Ad Details, 10 ads	10	20	$0.40
Total	11	24.8	$0.496

The detail calls dominate the cost. The search step costs less than one detail call. To hold the cost down, filter the search results on creativeType or on the headline first. Then fetch the detail of the shortlist only.

What does LinkedIn Ad Details return?

The response holds one element object with the ad. This block is an example response for a single-image ad from the advertiser UX Pilot AI.

{
  "query": {
    "url": "https://www.linkedin.com/ad-library/detail/1215501393"
  },
  "status": 200,
  "element": {
    "id": "1215501393",
    "about": {
      "format": "Single Image Ad",
      "paidBy": "UX Pilot",
      "advertiserUrl": "https://www.linkedin.com/company/99850535?trk=ad_library_about_ad_advertiser",
      "advertiserName": "UX Pilot AI"
    },
    "variants": [
      {
        "content": {
          "ctaLabel": "Learn more",
          "headline": "Generate wireframes in seconds",
          "imageUrl": "https://media.licdn.com/dms/image/v2/D4D10AQHrygtedL9DNQ/image-shrink_1280/B4DZXy8bxYHIAM-/0/1743537684174/Frame1000002823png?e=2147483647&v=beta&t=_j-yK4ZU0KcFUnEBpTGGtFYJED9-EoNv1SJGfdVWy2w",
          "targetUrl": null,
          "description": "Paste your PRD, generate multi-step flows with your actual components, and get screens that look like your product, in seconds, not generic AI output.\n\nSee it in action today."
        },
        "advertiser": {
          "name": "UX Pilot AI",
          "headline": "Promoted",
          "imageUrl": "https://media.licdn.com/dms/image/v2/D4E0BAQF14xfiQrSfew/company-logo_100_100/B4EZwpRV9cGcAQ-/0/1770218938904/uxpilot_ai_logo?e=1784160000&v=beta&t=dAJZSufW8CcVg1PVqad0K4AQtae4qg06TbFbHfRn-bE",
          "linkedinUrl": "https://www.linkedin.com/company/99850535?trk=ad_library_ad_preview_advertiser_image"
        },
        "creativeType": "SPONSORED_STATUS_UPDATE"
      }
    ],
    "targeting": null,
    "impressions": null
  }
}

What does each LinkedIn Ad Details response field mean?

Field	Type	Description
`query`	object	The lookup that RichAPI ran for the request.
`query.url`	string	The Ad Library detail URL that RichAPI read. It matches the `ad_url` parameter of the request.
`status`	integer	The status code of the Ad Library lookup. The value is `200` for a successful lookup.
`element`	object	The full ad. If RichAPI finds no ad for the URL, the value is null.
`element.id`	string	The numeric LinkedIn ad ID, for example `1215501393`.
`element.about`	object	The metadata of the ad: format, advertiser and run dates.
`element.about.format`	string	The ad format as named in the Ad Library, for example `Single Image Ad`.
`element.about.paidBy`	string	The name of the entity that paid for the ad. If an agency pays for the ad, the value differs from `advertiserName`.
`element.about.advertiserName`	string	The name of the advertiser as shown on the ad.
`element.about.advertiserUrl`	string	The LinkedIn company page URL of the advertiser.
`element.about.ranFrom`	string	The date on which the ad started to run.
`element.about.ranTo`	string	The date on which the ad stopped running.
`element.variants`	array	The creative variants of the ad. One ad can carry many variants.
`element.variants[].creativeType`	string	The creative type of the variant, for example `SPONSORED_STATUS_UPDATE`.
`element.variants[].content`	object	The creative content of the variant.
`element.variants[].content.headline`	string	The headline of the variant.
`element.variants[].content.description`	string	The full ad copy of the variant. Line breaks are `\n` characters.
`element.variants[].content.ctaLabel`	string	The call-to-action button label, for example `Learn more`.
`element.variants[].content.imageUrl`	string	The URL of the creative image of the variant.
`element.variants[].content.targetUrl`	string	The landing page URL of the variant. If the Ad Library hides the destination, the value is null.
`element.variants[].advertiser`	object	The advertiser identity as shown on the variant.
`element.variants[].advertiser.name`	string	The advertiser name on the variant. For a personal-profile ad, the value is the profile headline.
`element.variants[].advertiser.headline`	string	The promotion label under the advertiser name, for example `Promoted`.
`element.variants[].advertiser.imageUrl`	string	The logo or profile photo URL of the advertiser.
`element.variants[].advertiser.linkedinUrl`	string	The LinkedIn company page or profile URL of the advertiser.
`element.targeting`	object	The targeting criteria of the ad: `segments` and `parameters`. If LinkedIn publishes no targeting for the ad, the value is null.
`element.impressions`	object	The impression statistics of the ad: `total` and a `byCountry` breakdown. If LinkedIn publishes no impression data for the ad, the value is null.

When does LinkedIn Ad Details return targeting and impressions?

The LinkedIn Ad Library publishes targeting data and impression data for a subset of ads only. If the Ad Library publishes that data for the ad, LinkedIn Ad Details returns it in element.targeting and in element.impressions. For every other ad both fields hold null. The example response above is one such ad.

Read both fields defensively. If element.impressions is null, treat the reach of the ad as unknown. Do not treat null as zero impressions.

How much does LinkedIn Ad Details cost?

LinkedIn Ad Details costs 2 credits per call, and one call covers one ad. At $0.02 a credit, the rate on the 1,000 and 5,000 credit packs, one call costs $0.04. Larger packs cost less per credit. 500 calls cost 1,000 credits, and 1,000 credits cost $20.00.

Calls	Credits	Cost
1	2	$0.04
10	20	$0.40
100	200	$4.00
500	1,000	$20.00
1,000	2,000	$40.00
10,000	20,000	$400.00

RichAPI charges the 2 credits for every response with status 200. A response with a status outside the 200 range is refunded in full. A status 200 response with element set to null still costs 2 credits, because the lookup ran.

What errors does LinkedIn Ad Details return?

An error response holds an error field with a text message.

Status	Meaning	What to do
`400`	The request body failed validation.	Send the `ad_url` parameter with an Ad Library detail URL. Check the message for the field name.
`401`	The API key is missing, wrong or revoked.	Send your key in the `x-api-key` header.
`402`	The organization has no credits left, or the team reached its monthly spend limit.	Buy credits in the RichAPI dashboard, then send the request again.
`403`	This API key has no access to this endpoint (`Endpoint not available on your plan`).	Call `GET /api/v1/my-endpoints` to see the endpoints that this key can use. Contact support for access.
`404`	The endpoint name is wrong.	Send the request to `/linkedin_ad_details`.
`405`	The request used a method other than `POST`.	Send the request again with `POST` and a JSON request body.
`429`	Rate limit exceeded (too many requests per second).	Wait for the `Retry-After` seconds, then retry the request.
`500`	The API failed.	Send the request again. If the failure repeats, contact support.
`502`	The upstream data provider failed.	Send the request again after a short wait.
`504`	The upstream data provider timed out.	Send the request again after a short wait.

For a retry loop, wait 1 second, then 2 seconds, then 4 seconds between attempts.

Frequently asked questions

What input does the LinkedIn Ad Details API need?

The LinkedIn Ad Details API needs one LinkedIn Ad Library detail URL. Send it in the ad_url parameter of the request body, for example https://www.linkedin.com/ad-library/detail/1215501393.

Does the LinkedIn Ad Details API use GET or POST?

The LinkedIn Ad Details API uses POST. A GET request returns status 405 with the message linkedin_ad_details only supports POST.

Why does the LinkedIn Ad Details API return 400 for a url parameter?

The request body key is ad_url, and the API rejects every key that the schema does not name. A body that carries url returns status 400 with the message Unknown input field(s): url.

How much does the LinkedIn Ad Details API cost per ad?

The LinkedIn Ad Details API costs 2 credits per call, and one call covers one ad. 1,000 ads cost 2,000 credits, which is $40.00 at $0.02 a credit.

Why are the targeting and impressions fields null?

LinkedIn publishes targeting data and impression data for a subset of ads only. If the LinkedIn Ad Library shows no such data for an ad, element.targeting and element.impressions hold null. The call still costs 2 credits.

How do I find LinkedIn ad URLs for the LinkedIn Ad Details API?

Send LinkedIn Ad Search with the account_owner parameter, the keyword parameter or the countries parameter. Read the content.pageUrl field of each result in the elements array. Send each URL to LinkedIn Ad Details as the ad_url parameter.

Can the LinkedIn Ad Details API return many ads in one call?

No. The LinkedIn Ad Details API covers one ad per call. For many ads, send one call for each ad URL.

Is the LinkedIn Ad Details API synchronous?

Yes. The LinkedIn Ad Details API returns the ad in the same response. The endpoint needs no second call and no webhook.