> ## Documentation Index
> Fetch the complete documentation index at: https://leadmagic.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# B2B Ad Details
> Get detailed information about a specific B2B advertisement using its URL.
# B2B Ad Details
Get detailed information about a specific B2B professional network advertisement. Includes full creative content, video data, targeting, and performance metrics.
## Endpoint Details
| Metric | Value |
| -------------- | ------------------------ |
| **Cost** | **2 credits** per ad |
| **No Results** | **FREE** if ad not found |
Use the ad ID from [B2B Ads Search](/docs/v1/reference/b2b-ads-search) to get complete details.
### Per-Endpoint Limit
| Metric | Value |
| ------------------- | ------------------- |
| **Requests/Minute** | 300 |
| **Burst Capacity** | \~5 requests/second |
Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
***
## Quick Example
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST 'https://api.leadmagic.io/v1/ads/b2b-ads-details' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"ad_url": "https://www.linkedin.com/ad-library/detail/633872143"}'
```
```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://api.leadmagic.io/v1/ads/b2b-ads-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/633872143'
})
});
const data = await response.json();
console.log(`Ad headline: ${data.headline}`);
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
response = requests.post(
'https://api.leadmagic.io/v1/ads/b2b-ads-details',
headers={'X-API-Key': 'YOUR_API_KEY'},
json={'ad_url': 'https://www.linkedin.com/ad-library/detail/633872143'}
)
data = response.json()
print(f"Ad headline: {data.get('headline', 'N/A')}")
```
***
## Request Parameters
The Ad Library URL or ID (from B2B Ads Search).
Get the `ad_url` from the `link` field in [B2B Ads Search](/docs/v1/reference/b2b-ads-search) results.
***
## Response
Ad identifier
Ad headline
Full ad copy
Advertiser company info (name, profile URL)
Creative assets (images, videos)
Targeting criteria (if available)
When ad started
Impression range (if available)
Credits used (2 if found, 0 if not)
### Example Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"ad_id": "633872143",
"headline": "Transform your sales with AI",
"content": "Our platform helps sales teams close more deals with AI-powered insights...",
"advertiser": {
"name": "LeadMagic",
"profile_url": "linkedin.com/company/leadmagichq"
},
"creative": {
"image_url": "https://...",
"video_url": null,
"format": "single_image"
},
"targeting": {
"locations": ["United States", "Canada"],
"industries": ["Technology", "Finance"]
},
"started_running": "2026-01-15",
"impressions": {
"min": 10000,
"max": 50000
},
"credits_consumed": 2,
"message": "Ad details found."
}
```
***
## Success Messages
| Message | Meaning | Cost |
| ------------------- | --------------------------- | --------- |
| `Ad details found.` | Full ad data returned | 2 credits |
| `Ad not found.` | Ad doesn't exist or expired | FREE |
***
## Workflow
Use [B2B Ads Search](/docs/v1/reference/b2b-ads-search) to find ads for a company.
Extract the `link` field from search results.
Use this endpoint to get full creative and targeting data.
Study messaging, targeting, and creative approaches.
***
## Best Practices
Only fetch details for the most relevant ads from search results.
Targeting data reveals which audiences competitors prioritize.
Video URLs allow you to analyze video ad creative in detail.
***
## Use Cases
Study complete ad creative including video content.
Understand competitor audience targeting strategies.
Use impression data to benchmark ad performance.
Build detailed competitive advertising reports.
## OpenAPI
````yaml post /v1/ads/b2b-ads-details
openapi: 3.1.0
info:
title: LeadMagic API
version: 1.4.34
description: >
# LeadMagic API Documentation
The LeadMagic API provides comprehensive B2B data enrichment services
including email validation, email finding, profile search, company
intelligence, and more.
## Quick Start
1. Get your API key from the [LeadMagic Dashboard](https://app.leadmagic.io)
2. Add the `X-API-Key` header to all requests
3. Start enriching your data!
## Base URL
All API requests should be made to: `https://api.leadmagic.io`
## Rate Limits
Each endpoint has specific rate limits (requests per minute). Exceeding
limits returns a `429 Too Many Requests` response.
## Credits
API calls consume credits based on the endpoint used. Check your balance
with the `/v1/credits` endpoint.
## Support
Contact us at support@leadmagic.io for assistance.
contact:
name: LeadMagic Support
email: support@leadmagic.io
url: https://leadmagic.io
termsOfService: https://leadmagic.io/legal/terms
servers:
- url: https://api.leadmagic.io
description: Production API Server
security:
- ApiKeyAuth: []
tags:
- name: Credits
description: Manage and check your credit balance
- name: Analytics
description: >-
Monitor your API usage with comprehensive analytics endpoints (FREE - no
credits consumed)
- name: People Enrichment
description: Find and validate contact information for individuals
- name: Company Data
description: Discover company information and intelligence
- name: Jobs Data
description: Search job listings and detect career changes
- name: Ads Data
description: Search advertising data across platforms
paths:
/v1/ads/b2b-ads-details:
post:
tags:
- Ads Data
summary: B2B Ad Details
description: >-
Get detailed information about a specific B2B advertisement using its
URL.
operationId: b2b-ad-details
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ad_url:
type: string
description: The URL of the B2B advertisement from the ad library
default: 633872143
example: 633872143
required:
- ad_url
responses:
'200':
description: Successful response with ad details
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Ad details retrieved successfully
credits_consumed:
type: number
example: 2
ad_details:
type: object
description: >-
Detailed information about the ad (structure varies by ad
type)
properties:
ads_type:
type: string
example: Video Ad
content:
type: string
example: >-
Start your day knowing what deals you need to focus on
instead of opening up a dozen tabs in your CRM.
image:
type: string
nullable: true
heading:
type: string
example: Discover how our platform drives better sales outcomes
sub_heading:
type: string
nullable: true
availability_duration:
type: string
nullable: true
cta:
type: object
properties:
button_text:
type: string
example: Learn more
link:
type: string
example: >-
https://leadmagic.io/why-leadmagic/?trk=ad_library_ad_preview_headline_content
video:
type: object
properties:
video_thumbnail:
type: string
data_sources:
type: array
items:
type: object
properties:
type:
type: string
src:
type: string
bitrate:
type: number
total_impressions:
type: string
nullable: true
country_impressions:
type: array
items:
type: string
targeting_language:
type: string
nullable: true
targeting_location:
type: string
nullable: true
organization:
type: object
properties:
b2b_profile:
type: string
advertiser:
type: string
about_ad_paying_entity:
type: string
example:
message: Ad details retrieved successfully
credits_consumed: 2
ad_details:
ads_type: Video Ad
content: >-
Start your day knowing what deals you need to focus on
instead of opening up a dozen tabs in your CRM.
image: null
heading: Discover how our platform drives better sales outcomes
sub_heading: null
availability_duration: null
cta:
button_text: Learn more
link: >-
https://leadmagic.io/why-leadmagic/?trk=ad_library_ad_preview_headline_content
video:
video_thumbnail: >-
https://media.licdn.com/dms/image/v2/D4D10AQGzuzrGo4HoHw/videocover-high/videocover-high/0/1729725542194/InstantDemoStartofDaymp4?e=2147483647&v=beta&t=mu3nEXijLeoh_jU49uhAGqgEWlVrH5j7oT4B4UBgezk
data_sources:
- type: video/mp4
src: >-
https://dms.licdn.com/playlist/vid/v2/D4D10AQGzuzrGo4HoHw/progressive-servable-video/progressive-servable-video/0/1729725541436/InstantDemoStartofDaymp4?e=2147483647&v=beta&t=OIP5SAQ2zRwNyY97Sgh0RRDUZqZvFYW0MUDHP5F8Q54
bitrate: 6284199
- type: video/mp4
src: >-
https://dms.licdn.com/playlist/vid/v2/D4D10AQGzuzrGo4HoHw/mp4-640p-30fp-crf28/mp4-640p-30fp-crf28/0/1729725548053/InstantDemoStartofDaymp4?e=2147483647&v=beta&t=9cV-2R6MxcHoetYcg1Wuos9Wyi73haSAIgzlFFe4Izc
bitrate: 245220
- type: video/mp4
src: >-
https://dms.licdn.com/playlist/vid/v2/D4D10AQGzuzrGo4HoHw/mp4-360p-30fp-crf28/mp4-360p-30fp-crf28/0/1729725547788/InstantDemoStartofDaymp4?e=2147483647&v=beta&t=xSM4xV1YorfPdlNWuSYqg9nacRTLE0F_DkLzdK9mgdQ
bitrate: 109857
- type: video/mp4
src: >-
https://dms.licdn.com/playlist/vid/v2/D4D10AQGzuzrGo4HoHw/mp4-720p-30fp-crf28/mp4-720p-30fp-crf28/0/1729725549253/InstantDemoStartofDaymp4?e=2147483647&v=beta&t=f_bLk9pQQU8O5XoBapMPtqz-bZD6RQqTVLYkrYSAnlU
bitrate: 316022
total_impressions: null
country_impressions: []
targeting_language: null
targeting_location: null
organization:
b2b_profile: 10454372
advertiser: LeadMagic
about_ad_paying_entity: Paid for by LeadMagic Inc.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/InternalServerError'
components:
responses:
BadRequest:
description: |
Bad Request - The request was malformed or contains invalid parameters.
**Common causes:**
- Missing required fields
- Invalid field format (e.g., malformed email)
- Invalid JSON syntax
- Invalid parameter values
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ValidationError'
Unauthorized:
description: |
Unauthorized - Authentication failed.
**Common causes:**
- Missing X-API-Key header
- Invalid or expired API key
- Malformed API key
content:
application/problem+json:
schema:
oneOf:
- $ref: '#/components/schemas/MissingAuthenticationError'
- $ref: '#/components/schemas/InvalidApiKeyError'
PaymentRequired:
description: >
Payment Required - Insufficient credits for this request.
**Action required:** Add credits to your account at
https://app.leadmagic.io/billing
content:
application/problem+json:
schema:
$ref: '#/components/schemas/InsufficientCreditsError'
NotFound:
description: |
Not Found - The requested resource could not be found.
**Common causes:**
- Profile doesn't exist or is not accessible
- Company not found in our database
- Invalid URL or identifier
content:
application/problem+json:
schema:
oneOf:
- $ref: '#/components/schemas/ResourceNotFoundError'
- $ref: '#/components/schemas/ProfileNotFoundError'
RateLimitExceeded:
description: |
Too Many Requests - Rate limit exceeded.
**Action required:** Check the `Retry-After` header for when to retry.
**Headers returned:**
- `Retry-After`: Seconds until you can retry
- `RateLimit-Limit`: Your limit per minute
- `RateLimit-Remaining`: Remaining requests this minute
- `RateLimit-Reset`: Seconds until limit resets
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying
RateLimit-Limit:
schema:
type: integer
description: Maximum requests per minute
RateLimit-Remaining:
schema:
type: integer
description: Remaining requests this minute
RateLimit-Reset:
schema:
type: integer
description: Seconds until limit resets
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RateLimitExceededError'
InternalServerError:
description: >
Internal Server Error - Something went wrong on our end.
**Action required:** Wait 30 seconds and retry. If the problem persists,
contact support@leadmagic.io
content:
application/problem+json:
schema:
$ref: '#/components/schemas/InternalServerError'
schemas:
ValidationError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/validation_error
title: Request validation failed. Check your input parameters.
status: 400
code: validation_error
param:
- email
detail: 'Email format is invalid. Expected format: user@domain.com'
action: Provide a valid email address in the 'email' field.
docs: https://leadmagic.io/docs/api-reference/errors
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
MissingAuthenticationError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/missing_authentication
title: >-
Authentication required. Provide a valid API key in the X-API-Key
header (case-insensitive).
status: 401
code: missing_authentication
docs: https://leadmagic.io/docs/api-reference/authentication
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
InvalidApiKeyError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/invalid_api_key
title: Invalid API key. The key does not exist or is incorrect.
status: 401
code: invalid_api_key
docs: https://leadmagic.io/docs/api-reference/authentication
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
InsufficientCreditsError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/insufficient_credits
title: 'Insufficient credits: need 5, have 2.50. Add credits to continue.'
status: 402
code: insufficient_credits
detail: >-
This request requires 5 credit(s) but your account only has 2.50
credits remaining.
action: >-
Add credits to your account at https://app.leadmagic.io/billing or
contact support@leadmagic.io for enterprise plans.
docs: https://leadmagic.io/docs/api-reference/credits
context:
credits_required: 5
credits_available: 2.5
credits_needed: 2.5
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
ResourceNotFoundError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/resource_not_found
title: Resource not found.
status: 404
code: resource_not_found
docs: https://leadmagic.io/docs/api-reference/errors
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
ProfileNotFoundError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/profile_not_found
title: Profile not found or not accessible
status: 404
code: profile_not_found
docs: https://leadmagic.io/docs/api-reference/errors
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
RateLimitExceededError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/rate_limit_exceeded
title: >-
Rate limit exceeded: 300 requests per 1 minute. Wait and try
again.
status: 429
code: rate_limit_exceeded
detail: >-
You have exceeded the maximum allowed request rate. Please wait
before making additional requests.
action: >-
Wait 42 seconds before retrying. Consider implementing exponential
backoff.
docs: https://leadmagic.io/docs/api-reference/rate-limits
context:
limit: 300
window: 1 minute
remaining: 0
reset_at: 1706745642
retry_after_seconds: 42
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
InternalServerError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/INTERNAL_ERROR
title: >-
Something went wrong on our end. Our team has been notified and is
investigating.
status: 500
code: INTERNAL_ERROR
detail: >-
This is a temporary server error. The issue has been automatically
reported to our team.
action: >-
Wait 30 seconds and retry your request. If the problem persists,
contact support@leadmagic.io
docs: https://leadmagic.io/docs/api-reference/errors
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
ErrorResponse:
type: object
description: RFC 9457 Problem Details error response
required:
- success
- errors
properties:
success:
type: boolean
example: false
description: Always false for error responses
errors:
type: array
description: Array of error details (typically one, but can be multiple)
items:
$ref: '#/components/schemas/ErrorDetail'
meta:
$ref: '#/components/schemas/ResponseMeta'
ErrorDetail:
type: object
description: RFC 9457 compliant error detail
required:
- type
- title
- status
properties:
type:
type: string
format: uri
description: RFC 9457 - URI reference identifying the error type
example: https://api.leadmagic.io/errors/validation_error
title:
type: string
description: RFC 9457 - Short human-readable summary
example: Request validation failed. Check your input parameters.
status:
type: integer
description: RFC 9457 - HTTP status code
example: 400
detail:
type: string
description: RFC 9457 - Human-readable explanation specific to this occurrence
example: The email field is required but was not provided.
instance:
type: string
format: uri
description: RFC 9457 - URI reference for this specific occurrence
example: /v1/people/email-validation#req_abc123
code:
type: string
description: Machine-readable error code for programmatic handling
example: validation_error
param:
type: array
description: Parameters that caused the error
items:
type: string
example:
- email
action:
type: string
description: Suggested action to resolve the error
example: Provide a valid email address in the 'email' field.
docs:
type: string
format: uri
description: Link to relevant documentation
example: https://leadmagic.io/docs/api-reference/errors
context:
type: object
description: Additional context specific to this error type
additionalProperties: true
ResponseMeta:
type: object
description: Metadata included in all responses
properties:
request_id:
type: string
format: uuid
description: Unique identifier for this request (use for debugging/support)
example: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp when the response was generated
example: '2024-02-01T12:00:00.000Z'
environment:
type: string
description: API environment (production, staging)
example: production
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
Your LeadMagic API key. Header name is case-insensitive (X-API-Key,
X-API-KEY, x-api-key all work).
````