Ads ad API

Get one ad's details from Meta, Google, TikTok, LinkedIn, Microsoft or Pinterest

curl --request POST \
  --url https://api.stophy.dev/v1/ads/ad \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ad": "<string>",
  "network": "meta"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({ad: '<string>', network: 'meta'})
};

fetch('https://api.stophy.dev/v1/ads/ad', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.stophy.dev/v1/ads/ad"

payload = {
    "ad": "<string>",
    "network": "meta"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "data": {
    "adUrl": "<string>",
    "isActive": true,
    "versions": 0,
    "adId": "<string>",
    "pageId": "<string>",
    "pageName": "<string>",
    "pageUrl": "<string>",
    "pageAvatarUrl": "<string>",
    "pageCategories": [
      "<string>"
    ],
    "pageLikes": 0,
    "firstShownAt": "2023-11-07T05:31:56Z",
    "lastShownAt": "2023-11-07T05:31:56Z",
    "platforms": [
      "<string>"
    ],
    "format": "<string>",
    "text": "<string>",
    "linkUrl": "<string>",
    "linkTitle": "<string>",
    "linkDescription": "<string>",
    "ctaText": "<string>",
    "imageUrls": [
      "<string>"
    ],
    "videoUrls": [
      "<string>"
    ],
    "cards": [
      {
        "text": "<string>",
        "linkUrl": "<string>",
        "linkTitle": "<string>",
        "ctaText": "<string>",
        "imageUrl": "<string>",
        "videoUrl": "<string>"
      }
    ],
    "categories": [
      "<string>"
    ],
    "paidBy": "<string>",
    "spendMin": 0,
    "spendMax": 0,
    "spendCurrency": "<string>",
    "impressionsMin": 0,
    "impressionsMax": 0,
    "reachMin": 0,
    "reachMax": 0,
    "countries": [
      "<string>"
    ],
    "advertiserDescription": "<string>",
    "advertiserCategory": "<string>",
    "advertiserVerification": "<string>",
    "advertiserInstagram": "<string>",
    "advertiserInstagramFollowers": 0,
    "audienceAgeGender": [
      {
        "female": 123,
        "male": 123,
        "unknown": 123,
        "age": "<string>"
      }
    ],
    "audienceRegions": [
      {
        "share": 123,
        "region": "<string>"
      }
    ],
    "euReachTotal": 0,
    "euReachByCountry": [
      {
        "female": 0,
        "male": 0,
        "unknown": 0,
        "country": "<string>",
        "age": "<string>"
      }
    ],
    "payers": [
      {
        "paidBy": "<string>",
        "beneficiary": "<string>"
      }
    ]
  },
  "creditsUsed": 123,
  "requestId": "<string>"
}

{
  "success": false,
  "error": {
    "code": "agentCodeCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123,
    "requiredCredits": 123,
    "availableCredits": 123,
    "billingUrl": "https://stophy.dev/billing"
  }
}

{
  "success": false,
  "error": {
    "code": "agentCodeCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123,
    "requiredCredits": 123,
    "availableCredits": 123,
    "billingUrl": "https://stophy.dev/billing"
  }
}

POST

ads

Get one ad's details from Meta, Google, TikTok, LinkedIn, Microsoft or Pinterest

curl --request POST \
  --url https://api.stophy.dev/v1/ads/ad \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ad": "<string>",
  "network": "meta"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({ad: '<string>', network: 'meta'})
};

fetch('https://api.stophy.dev/v1/ads/ad', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.stophy.dev/v1/ads/ad"

payload = {
    "ad": "<string>",
    "network": "meta"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "data": {
    "adUrl": "<string>",
    "isActive": true,
    "versions": 0,
    "adId": "<string>",
    "pageId": "<string>",
    "pageName": "<string>",
    "pageUrl": "<string>",
    "pageAvatarUrl": "<string>",
    "pageCategories": [
      "<string>"
    ],
    "pageLikes": 0,
    "firstShownAt": "2023-11-07T05:31:56Z",
    "lastShownAt": "2023-11-07T05:31:56Z",
    "platforms": [
      "<string>"
    ],
    "format": "<string>",
    "text": "<string>",
    "linkUrl": "<string>",
    "linkTitle": "<string>",
    "linkDescription": "<string>",
    "ctaText": "<string>",
    "imageUrls": [
      "<string>"
    ],
    "videoUrls": [
      "<string>"
    ],
    "cards": [
      {
        "text": "<string>",
        "linkUrl": "<string>",
        "linkTitle": "<string>",
        "ctaText": "<string>",
        "imageUrl": "<string>",
        "videoUrl": "<string>"
      }
    ],
    "categories": [
      "<string>"
    ],
    "paidBy": "<string>",
    "spendMin": 0,
    "spendMax": 0,
    "spendCurrency": "<string>",
    "impressionsMin": 0,
    "impressionsMax": 0,
    "reachMin": 0,
    "reachMax": 0,
    "countries": [
      "<string>"
    ],
    "advertiserDescription": "<string>",
    "advertiserCategory": "<string>",
    "advertiserVerification": "<string>",
    "advertiserInstagram": "<string>",
    "advertiserInstagramFollowers": 0,
    "audienceAgeGender": [
      {
        "female": 123,
        "male": 123,
        "unknown": 123,
        "age": "<string>"
      }
    ],
    "audienceRegions": [
      {
        "share": 123,
        "region": "<string>"
      }
    ],
    "euReachTotal": 0,
    "euReachByCountry": [
      {
        "female": 0,
        "male": 0,
        "unknown": 0,
        "country": "<string>",
        "age": "<string>"
      }
    ],
    "payers": [
      {
        "paidBy": "<string>",
        "beneficiary": "<string>"
      }
    ]
  },
  "creditsUsed": 123,
  "requestId": "<string>"
}

{
  "success": false,
  "error": {
    "code": "agentCodeCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123,
    "requiredCredits": 123,
    "availableCredits": 123,
    "billingUrl": "https://stophy.dev/billing"
  }
}

{
  "success": false,
  "error": {
    "code": "agentCodeCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123,
    "requiredCredits": 123,
    "availableCredits": 123,
    "billingUrl": "https://stophy.dev/billing"
  }
}

Endpoint: ads.ad
Returns: data has adId, adUrl, pageId, pageName, pageUrl, pageAvatarUrl, pageCategories, pageLikes, isActive, firstShownAt, lastShownAt, platforms, format, text, linkUrl, linkTitle, linkDescription, ctaText, imageUrls, videoUrls, cards, versions, categories, paidBy, spendMin, spendMax, spendCurrency, impressionsMin, impressionsMax, reachMin, reachMax, countries, advertiserDescription, advertiserCategory, advertiserVerification, advertiserInstagram, advertiserInstagramFollowers, audienceAgeGender, audienceRegions, euReachTotal, euReachByCountry, payers, advertiserId, advertiserName, advertiserUrl, domain, daysShown, previewUrl, imageUrl, advertiserCountry, advertiserIsVerified, variations, regions, targetingIncluded, targetingExcluded, headline, videoUrl, thumbnailUrl, objective, category, audienceSizeMin, audienceSizeMax, languages, interests, creativeType, advertiserAvatarUrl, postedBy, targeting, targetingUsed, linkCaption, advertisers, links, reachByCountry, ageRanges, genders, audienceTypes, isCommercial.
Cost: 2 credits per call. Failed calls cost nothing.
Paging: No.

Example

import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.ads.ad({ network: "meta", ad: "1234567890123456" });
console.log(result.data);

from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.ads.ad(network="meta", ad="1234567890123456")
print(result["data"])

curl -X POST https://api.stophy.dev/v1/ads/ad \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"network":"meta","ad":"1234567890123456"}'

stophy ads ad 1234567890123456 --network meta

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

string

required

network

string

required

Allowed value: "meta"

Response

The data, and the credits this call used.

success

any

required

data

object

required

Show child attributes

creditsUsed

integer

required

requestId

string

required

Using the API

Catalog

Account

Web search and pages

Video

Social

Places and travel

Shopping

Apps

Jobs

Real estate

Ads

Finance and crypto

Example

Authorizations

Body

Response

​Example

Authorizations

Body

Response

Example