Unlock Powerful Insights with the Social Media Ad Insights API
15 Jun 2025
The Social Media Ad Insights API is designed to help developers seamlessly integrate social media advertising data into their applications. With this API, you can automate the retrieval of critical information about advertising campaigns, making it easier to analyze performance, optimize strategies, and enhance overall marketing efforts. The API provides a suite of Cognitive Actions that simplify the process of gathering insights from social media platforms, allowing you to focus on what matters most: driving results.
Common Use Cases
- Marketing Analytics: Track and analyze the performance of advertising campaigns across various social media platforms.
- Competitive Analysis: Gather insights on competitors' advertising strategies to inform your own campaigns.
- Ad Optimization: Identify successful ad formats and strategies to replicate or enhance in future campaigns.
- Data-Driven Decisions: Use insights to make informed decisions about budget allocation and target audience engagement.
Before diving in, ensure you have your Cognitive Actions API key and a basic understanding of making API calls.
Retrieve LinkedIn Page ID
The Retrieve LinkedIn Page ID action allows you to fetch the LinkedIn Page ID for a specified company name. This is particularly useful for advertisers looking to connect their campaigns with the appropriate LinkedIn profiles for enhanced targeting and analysis.
- Input Requirements:
companyName(string): The name of the company to query (e.g., "starbucks").
- Expected Output:
page_id: The LinkedIn Page ID associated with the company.company_name: The name of the company used in the query.
- Use Cases for this Action:
- Quickly link advertising efforts with company profiles on LinkedIn.
- Validate the existence of a company profile before launching campaigns.
```python
import requests
import json
# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"
action_id = "5c9567e6-a4f7-49f2-891a-10563c2de432" # Action ID for: Retrieve LinkedIn Page ID
# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
"companyName": "starbucks"
}
headers = {
"Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
"Content-Type": "application/json",
# Add any other required headers for the Cognitive Actions API
}
# Prepare the request body for the hypothetical execution endpoint
request_body = {
"action_id": action_id,
"inputs": payload
}
print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")
try:
response = requests.post(
COGNITIVE_ACTIONS_EXECUTE_URL,
headers=headers,
json=request_body
)
response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)
result = response.json()
print("Action executed successfully. Result:")
print(json.dumps(result, indent=2))
except requests.exceptions.RequestException as e:
print(f"Error executing action {action_id}: {e}")
if e.response is not None:
print(f"Response status: {e.response.status_code}")
try:
print(f"Response body: {e.response.json()}")
except json.JSONDecodeError:
print(f"Response body (non-JSON): {e.response.text}")
print("------------------------------------------------")
## Retrieve Advertiser Ads
The **Retrieve Advertiser Ads** action enables you to fetch a list of advertising campaigns associated with a specific advertiser. You can apply various filters such as date range, country, and ad format, making it easier to refine your data retrieval.
- **Input Requirements:**
- `advertiserIdentifier` (string): A unique identifier for the advertiser (required).
- Optional parameters include `limit`, `format`, `countryCode`, `startingPeriod`, and `endingPeriod`.
- **Expected Output:**
- An array of ads including details such as `advertiser_id`, `total_ad_count`, and `country_code`.
- **Use Cases for this Action:**
- Analyze the performance of your advertising campaigns over specific periods.
- Filter results by country or ad format to identify trends and performance metrics.
```markdown
```python
import requests
import json
# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"
action_id = "5dff16a9-b3c3-48f7-9d77-9c8e555cd8f7" # Action ID for: Retrieve Advertiser Ads
# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
"limit": "40",
"format": "ALL",
"countryCode": "US",
"advertiserIdentifier": "AR00604964697900318721"
}
headers = {
"Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
"Content-Type": "application/json",
# Add any other required headers for the Cognitive Actions API
}
# Prepare the request body for the hypothetical execution endpoint
request_body = {
"action_id": action_id,
"inputs": payload
}
print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")
try:
response = requests.post(
COGNITIVE_ACTIONS_EXECUTE_URL,
headers=headers,
json=request_body
)
response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)
result = response.json()
print("Action executed successfully. Result:")
print(json.dumps(result, indent=2))
except requests.exceptions.RequestException as e:
print(f"Error executing action {action_id}: {e}")
if e.response is not None:
print(f"Response status: {e.response.status_code}")
try:
print(f"Response body: {e.response.json()}")
except json.JSONDecodeError:
print(f"Response body (non-JSON): {e.response.text}")
print("------------------------------------------------")
## Search Ads by Query
The **Search Ads by Query** action allows users to perform a targeted search for ads based on a user-specified query. This action supports localization via a country code and enables pagination for results.
- **Input Requirements:**
- `query` (string): The search term (e.g., "iPhone").
- Optional parameters include `countryCode` and `continuationToken`.
- **Expected Output:**
- A list of ads matching the query, including ad details and metadata.
- **Use Cases for this Action:**
- Discover ads related to specific products or keywords in the market.
- Assess competitor advertising strategies by searching for common terms.
```markdown
```python
import requests
import json
# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"
action_id = "6e84ac31-db5f-43dd-a7a7-cb2d5f3b64a5" # Action ID for: Search Ads by Query
# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
"query": "iPhone",
"countryCode": "US"
}
headers = {
"Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
"Content-Type": "application/json",
# Add any other required headers for the Cognitive Actions API
}
# Prepare the request body for the hypothetical execution endpoint
request_body = {
"action_id": action_id,
"inputs": payload
}
print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")
try:
response = requests.post(
COGNITIVE_ACTIONS_EXECUTE_URL,
headers=headers,
json=request_body
)
response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)
result = response.json()
print("Action executed successfully. Result:")
print(json.dumps(result, indent=2))
except requests.exceptions.RequestException as e:
print(f"Error executing action {action_id}: {e}")
if e.response is not None:
print(f"Response status: {e.response.status_code}")
try:
print(f"Response body: {e.response.json()}")
except json.JSONDecodeError:
print(f"Response body (non-JSON): {e.response.text}")
print("------------------------------------------------")
## Retrieve Advertiser Information
This action fetches detailed information for a specific advertiser using their unique identifier. It's designed for extracting insights from social media ad libraries.
- **Input Requirements:**
- `advertiserId` (string): A unique identifier for the advertiser (required).
- **Expected Output:**
- Detailed information about the advertiser, including their name, status, and performance metrics.
- **Use Cases for this Action:**
- Gain insights into specific advertisers to inform your marketing strategies.
- Compare performance metrics across different advertisers to identify best practices.
```markdown
```python
import requests
import json
# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"
action_id = "980a2535-3262-4a8e-a229-344af7903d5d" # Action ID for: Retrieve Advertiser Information
# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
"advertiserId": "AR00604964697900318721"
}
headers = {
"Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
"Content-Type": "application/json",
# Add any other required headers for the Cognitive Actions API
}
# Prepare the request body for the hypothetical execution endpoint
request_body = {
"action_id": action_id,
"inputs": payload
}
print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")
try:
response = requests.post(
COGNITIVE_ACTIONS_EXECUTE_URL,
headers=headers,
json=request_body
)
response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)
result = response.json()
print("Action executed successfully. Result:")
print(json.dumps(result, indent=2))
except requests.exceptions.RequestException as e:
print(f"Error executing action {action_id}: {e}")
if e.response is not None:
print(f"Response status: {e.response.status_code}")
try:
print(f"Response body: {e.response.json()}")
except json.JSONDecodeError:
print(f"Response body (non-JSON): {e.response.text}")
print("------------------------------------------------")
## Execute Page Search
The **Execute Page Search** action allows users to perform a search on pages based on a given query and country code. This action is ideal for retrieving social media ad information related to specific domains.
- **Input Requirements:**
- `query` (string): The search term used in the query (e.g., "apple").
- Optional parameters include `countryCode`, `maxResults`, and `contentType`.
- **Expected Output:**
- A list of relevant pages, including details such as `page_id`, `category`, and `likes`.
- **Use Cases for this Action:**
- Identify social media pages related to specific products or brands.
- Analyze the popularity and engagement of competitor pages.
```markdown
```python
import requests
import json
# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"
action_id = "9c2e1c21-ad7b-4108-b427-dec048881104" # Action ID for: Execute Page Search
# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
"query": "apple",
"countryISOCode": "US"
}
headers = {
"Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
"Content-Type": "application/json",
# Add any other required headers for the Cognitive Actions API
}
# Prepare the request body for the hypothetical execution endpoint
request_body = {
"action_id": action_id,
"inputs": payload
}
print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")
try:
response = requests.post(
COGNITIVE_ACTIONS_EXECUTE_URL,
headers=headers,
json=request_body
)
response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)
result = response.json()
print("Action executed successfully. Result:")
print(json.dumps(result, indent=2))
except requests.exceptions.RequestException as e:
print(f"Error executing action {action_id}: {e}")
if e.response is not None:
print(f"Response status: {e.response.status_code}")
try:
print(f"Response body: {e.response.json()}")
except json.JSONDecodeError:
print(f"Response body (non-JSON): {e.response.text}")
print("------------------------------------------------")
## Search Ads by Domain
The **Search Ads by Domain** action retrieves social media advertisements by querying specific domain names. This action allows for tailored ad search results based on various criteria.
- **Input Requirements:**
- `domain` (string): The primary domain name to query (e.g., "apple.com").
- Optional parameters include `pageToken`, `maxResults`, and `contentType`.
- **Expected Output:**
- A list of ads associated with the queried domain, including ad details and metadata.
- **Use Cases for this Action:**
- Track advertising campaigns related to specific domain names.
- Analyze trends and performance metrics for ads associated with your or competitors' domains.
```markdown
```python
import requests
import json
# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"
action_id = "a6b95a15-480b-4213-aaf6-5ed0c03a5b11" # Action ID for: Search Ads by Domain
# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
"domain": "apple.com",
"maxResults": "40",
"contentType": "ALL",
"countryCode": "US"
}
headers = {
"Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
"Content-Type": "application/json",
# Add any other required headers for the Cognitive Actions API
}
# Prepare the request body for the hypothetical execution endpoint
request_body = {
"action_id": action_id,
"inputs": payload
}
print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")
try:
response = requests.post(
COGNITIVE_ACTIONS_EXECUTE_URL,
headers=headers,
json=request_body
)
response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)
result = response.json()
print("Action executed successfully. Result:")
print(json.dumps(result, indent=2))
except requests.exceptions.RequestException as e:
print(f"Error executing action {action_id}: {e}")
if e.response is not None:
print(f"Response status: {e.response.status_code}")
try:
print(f"Response body: {e.response.json()}")
except json.JSONDecodeError:
print(f"Response body (non-JSON): {e.response.text}")
print("------------------------------------------------")
## Retrieve Supported Countries
The **Retrieve Supported Countries** action fetches a list of countries supported by the Social Media Ad Library, helping users identify where specific ad features are available.
- **Input Requirements:**
- No specific parameters required.
- **Expected Output:**
- An array of ISO country codes representing the supported countries.
- **Use Cases for this Action:**
- Ensure your advertising strategies are compliant with regional regulations.
- Identify potential markets for your advertising campaigns based on country support.
```markdown
```python
import requests
import json
# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"
action_id = "e696e1ca-0247-419c-9dba-a0023fb47d01" # Action ID for: Retrieve Supported Countries
# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {}
headers = {
"Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
"Content-Type": "application/json",
# Add any other required headers for the Cognitive Actions API
}
# Prepare the request body for the hypothetical execution endpoint
request_body = {
"action_id": action_id,
"inputs": payload
}
print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")
try:
response = requests.post(
COGNITIVE_ACTIONS_EXECUTE_URL,
headers=headers,
json=request_body
)
response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)
result = response.json()
print("Action executed successfully. Result:")
print(json.dumps(result, indent=2))
except requests.exceptions.RequestException as e:
print(f"Error executing action {action_id}: {e}")
if e.response is not None:
print(f"Response status: {e.response.status_code}")
try:
print(f"Response body: {e.response.json()}")
except json.JSONDecodeError:
print(f"Response body (non-JSON): {e.response.text}")
print("------------------------------------------------")
## Conclusion
The **Social Media Ad Insights API** offers powerful capabilities for developers looking to leverage advertising data for better marketing insights. By integrating these Cognitive Actions into your applications, you can automate data retrieval, enhance analytics, and optimize marketing strategies effectively. Start utilizing these actions today to unlock the full potential of your social media advertising efforts!