> ## 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.
# Google Ads Search
> Search for Google Ads run by a company to understand their advertising strategy.
# Google Ads
Search for Google Ads run by a company. Analyze competitor advertising strategies, messaging, and creative approaches.
## Endpoint Details
| Metric | Value |
| --------------- | -------------------------- |
| **Cost** | **0.2 credits** per search |
| **Calculation** | 5 searches = 1 credit |
| **No Results** | **FREE** if no ads found |
Very cost-effective for competitive ad intelligence at just 0.2 credits per search.
### 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/google-ads-search' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"company_domain": "leadmagic.io"}'
```
```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://api.leadmagic.io/v1/ads/google-ads-search', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({ company_domain: 'leadmagic.io' })
});
const data = await response.json();
console.log(`Found ${data.ads?.length || 0} ads`);
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
response = requests.post(
'https://api.leadmagic.io/v1/ads/google-ads-search',
headers={'X-API-Key': 'YOUR_API_KEY'},
json={'company_domain': 'leadmagic.io'}
)
data = response.json()
print(f"Found {len(data.get('ads', []))} ads")
```
***
## Request Parameters
Company website domain (preferred).
Company name.
You must provide either `company_domain` or `company_name` (or both).
***
## Response
Company searched
Array of ad creatives
Credits used (0.2 if found, 0 if not)
Human-readable status message
### Ad Object
| Field | Type | Description |
| ------------- | ------ | ----------------------------------- |
| `headline` | string | Ad headline |
| `description` | string | Ad description |
| `display_url` | string | Display URL |
| `final_url` | string | Landing page URL |
| `ad_type` | string | Type of ad (text, responsive, etc.) |
### Example Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"company_name": "Example Robotics",
"ads": [
{
"headline": "Free CRM Software | Example Robotics",
"description": "Get started with free CRM. No credit card required.",
"display_url": "leadmagic.io",
"final_url": "https://leadmagic.io",
"ad_type": "responsive_search"
}
],
"credits_consumed": 0.2,
"message": "Ads found."
}
```
***
## Success Messages
| Message | Meaning | Cost |
| -------------------------------- | ------------------------ | ----------- |
| `Ads found.` | Google Ads data returned | 0.2 credits |
| `No ads found for this company.` | No Google Ads found | FREE |
***
## Best Practices
Study headlines and descriptions to understand positioning and value props.
Use final\_urls to analyze competitor landing pages.
Regular monitoring reveals A/B tests and strategy shifts.
***
## Use Cases
Understand competitor ad strategies and messaging.
Find proven messaging patterns in your market.
Analyze advertising trends in your industry.
Discover competitor landing pages and offers.
## OpenAPI
````yaml post /v1/ads/google-ads-search
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/google-ads-search:
post:
tags:
- Ads Data
summary: Google Ads Search
description: >-
Search for Google Ads run by a company to understand their advertising
strategy.
operationId: google-ads-search
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
company_domain:
type: string
description: Company domain name
default: leadmagic.io
example: leadmagic.io
company_name:
type: string
description: Company name
default: leadmagic
example: leadmagic
responses:
'200':
description: Successful response with ads details
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Google Ads retrieved successfully
credits_consumed:
type: number
example: 0.2
ads_count:
type: integer
example: 2
ads:
type: array
items:
type: object
properties:
advertiser_id:
type: string
example: '123456'
creative_id:
type: string
example: '789012'
original_url:
type: string
example: https://www.example.com/ad
variants:
type: array
items:
type: object
properties:
content:
type: string
example: >-
height:
type: integer
nullable: true
example: 173
width:
type: integer
nullable: true
example: 380
start:
type: string
example: '2023-01-01'
last_seen:
type: string
example: '2023-12-31'
advertiser_name:
type: string
example: Example Company
format:
type: string
example: Text
example:
ads:
- advertiser_id: AR14106062795078369281
creative_id: CR14003695067076755457
original_url: >-
https://adstransparency.google.com/advertiser/AR14106062795078369281/creative/CR14003695067076755457?region=anywhere
variants:
- content: >-
height: 173
width: 380
start: '2024-07-03'
last_seen: '2025-03-06'
advertiser_name: LeadMagic Inc
format: Text
- advertiser_id: AR14106062795078369281
creative_id: CR16065875974473908225
original_url: >-
https://adstransparency.google.com/advertiser/AR14106062795078369281/creative/CR16065875974473908225?region=anywhere
variants:
- content: >-
height: 173
width: 380
start: '2025-02-04'
last_seen: '2025-03-06'
advertiser_name: LeadMagic Inc
format: Text
credits_consumed: 8
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'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'
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'
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).
````