Meta search ads API

Search ads in the Meta ad library

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

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: 'nike', limit: 20})
};

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

import requests

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

payload = {
    "query": "nike",
    "limit": 20
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "success": true,
  "data": {
    "ads": [
      {
        "url": "<string>",
        "isActive": true,
        "versions": 0,
        "id": "<string>",
        "page": {
          "id": "<string>",
          "name": "<string>",
          "url": "<string>",
          "avatar": "<string>",
          "categories": [
            "<string>"
          ],
          "likes": 0
        },
        "firstShownAt": "2023-11-07T05:31:56Z",
        "lastShownAt": "2023-11-07T05:31:56Z",
        "platforms": [
          "<string>"
        ],
        "format": "<string>",
        "text": "<string>",
        "link": {
          "url": "<string>",
          "title": "<string>",
          "description": "<string>",
          "caption": "<string>"
        },
        "cta": {
          "text": "<string>",
          "type": "<string>"
        },
        "images": [
          {
            "url": "<string>",
            "caption": "<string>",
            "alt": "<string>"
          }
        ],
        "videos": [
          {
            "url": "<string>",
            "thumbnail": "<string>"
          }
        ],
        "cards": [
          {
            "text": "<string>",
            "link": {
              "url": "<string>",
              "title": "<string>",
              "description": "<string>",
              "caption": "<string>"
            },
            "cta": {
              "text": "<string>",
              "type": "<string>"
            },
            "image": "<string>",
            "video": {
              "url": "<string>",
              "thumbnail": "<string>"
            }
          }
        ],
        "categories": [
          "<string>"
        ],
        "paidBy": "<string>",
        "spend": {
          "min": 0,
          "max": 0
        },
        "currency": "<string>",
        "impressions": {
          "min": 0,
          "max": 0
        },
        "reach": {
          "min": 0,
          "max": 0
        },
        "countries": [
          "<string>"
        ]
      }
    ],
    "cursor": "<string>"
  },
  "creditsUsed": 123,
  "requestId": "<string>"
}

{
  "success": false,
  "error": {
    "code": "cliSessionCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123
  }
}

{
  "success": false,
  "error": {
    "code": "cliSessionCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123
  }
}

POST

meta

ads

Search ads in the Meta ad library

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

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: 'nike', limit: 20})
};

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

import requests

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

payload = {
    "query": "nike",
    "limit": 20
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "success": true,
  "data": {
    "ads": [
      {
        "url": "<string>",
        "isActive": true,
        "versions": 0,
        "id": "<string>",
        "page": {
          "id": "<string>",
          "name": "<string>",
          "url": "<string>",
          "avatar": "<string>",
          "categories": [
            "<string>"
          ],
          "likes": 0
        },
        "firstShownAt": "2023-11-07T05:31:56Z",
        "lastShownAt": "2023-11-07T05:31:56Z",
        "platforms": [
          "<string>"
        ],
        "format": "<string>",
        "text": "<string>",
        "link": {
          "url": "<string>",
          "title": "<string>",
          "description": "<string>",
          "caption": "<string>"
        },
        "cta": {
          "text": "<string>",
          "type": "<string>"
        },
        "images": [
          {
            "url": "<string>",
            "caption": "<string>",
            "alt": "<string>"
          }
        ],
        "videos": [
          {
            "url": "<string>",
            "thumbnail": "<string>"
          }
        ],
        "cards": [
          {
            "text": "<string>",
            "link": {
              "url": "<string>",
              "title": "<string>",
              "description": "<string>",
              "caption": "<string>"
            },
            "cta": {
              "text": "<string>",
              "type": "<string>"
            },
            "image": "<string>",
            "video": {
              "url": "<string>",
              "thumbnail": "<string>"
            }
          }
        ],
        "categories": [
          "<string>"
        ],
        "paidBy": "<string>",
        "spend": {
          "min": 0,
          "max": 0
        },
        "currency": "<string>",
        "impressions": {
          "min": 0,
          "max": 0
        },
        "reach": {
          "min": 0,
          "max": 0
        },
        "countries": [
          "<string>"
        ]
      }
    ],
    "cursor": "<string>"
  },
  "creditsUsed": 123,
  "requestId": "<string>"
}

{
  "success": false,
  "error": {
    "code": "cliSessionCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123
  }
}

{
  "success": false,
  "error": {
    "code": "cliSessionCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123
  }
}

Endpoint: meta.ads.search
Returns: data has ads.
Cost: 2 credits per 10 items, at least 2 credits. Failed calls cost nothing.
Paging: Yes. Send the cursor from the response to get the next page. See Paging.

Example

import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.meta.ads.search({ query: "nike", limit: 20 });
console.log(result.data.ads);

from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.meta.ads.search(query="nike", limit=20)
print(result["data"]["ads"])

curl -X POST https://api.stophy.dev/v1/meta/ads/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nike","limit":20}'

stophy meta ads search nike --limit 20

Authorizations

Authorization

string

header

required

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

Body

application/json

query

string

required

Required string length: 1 - 200

country

string

default:us

ISO 3166-1 alpha-2 country code, or all. Any case is accepted.

Pattern: ^(?:[A-Za-z]{2}|[Aa][Ll][Ll])$

adType

enum<string>

default:all

Available options:

all,

politicalAndIssue

status

enum<string>

default:active

Available options:

active,

inactive,

all

mediaType

enum<string>

default:all

Available options:

all,

image,

video,

meme,

none

platforms

enum<string>[]

Maximum array length: 4

Available options:

facebook,

instagram,

messenger,

audienceNetwork

from

string<date>

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$

string<date>

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$

language

string

BCP 47 language tag, e.g. en or pt-BR. Any case is accepted.

Pattern: ^[A-Za-z]{2}$

limit

integer

default:30

Required range: 1 <= x <= 500

cursor

string

Pattern: ^(?:\d{1,4}~(?:[\w-]{10,500})?|(?:[\w-]{10,500}))$

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

Meta search ads API

Example

Authorizations

Body

Response

​Example

Authorizations

Body

Response

Example