> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Ads

> Search the public ad libraries of Meta, Google, TikTok, LinkedIn, Pinterest, Microsoft, and Snapchat. Get each ad's creative and copy.

Search the public ad libraries of Meta, Google, TikTok, LinkedIn, Pinterest, Microsoft, and Snapchat. Get each ad's creative and copy. See every field in the [Ads reference](/api-reference/endpoint/meta-ads-search), or try it in the [playground](https://stophy.dev/playground).

## Search ads in the Meta ad library

<CodeGroup>
  ```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
  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);
  ```

  ```python Python icon="python" theme={null}
  from stophy import Stophy

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

  ```bash cURL icon="terminal" theme={null}
  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}'
  ```

  ```bash CLI icon="square-terminal" theme={null}
  stophy meta ads search nike --limit 20
  ```
</CodeGroup>

The response:

```json theme={null}
{
  "success": true,
  "data": {
    "ads": [
      {
        "id": "abc123",
        "url": "https://example.com/",
        "page": {
          "id": "abc123",
          "name": "Example title",
          "url": "https://example.com/",
          "avatar": "https://example.com/image.jpg",
          "categories": [
            "example"
          ],
          "likes": 1234
        },
        "isActive": false,
        "firstShownAt": "2026-09-28T12:00:00.000Z",
        "lastShownAt": "2026-09-28T12:00:00.000Z",
        "platforms": [
          "example"
        ],
        "format": "example",
        "text": "A short, readable summary of the result.",
        "link": {
          "url": "https://example.com/",
          "title": "Example title",
          "description": "A short, readable summary of the result.",
          "caption": "example"
        },
        "cta": {
          "text": "A short, readable summary of the result.",
          "type": "example"
        },
        "images": [
          {
            "url": "https://example.com/",
            "caption": "example",
            "alt": "example"
          }
        ],
        "videos": [
          {
            "url": "https://example.com/",
            "thumbnail": "https://example.com/image.jpg"
          }
        ],
        "cards": [
          {
            "text": "A short, readable summary of the result.",
            "link": {
              "url": "https://example.com/",
              "title": "Example title",
              "description": "A short, readable summary of the result.",
              "caption": "example"
            },
            "cta": {
              "text": "A short, readable summary of the result.",
              "type": "example"
            },
            "image": "https://example.com/image.jpg",
            "video": {
              "url": "https://example.com/",
              "thumbnail": "https://example.com/image.jpg"
            }
          }
        ],
        "versions": 1,
        "categories": [
          "example"
        ],
        "paidBy": "example",
        "spend": {
          "min": 1,
          "max": 1
        },
        "currency": "USD",
        "impressions": {
          "min": 1,
          "max": 1
        },
        "reach": {
          "min": 1,
          "max": 1
        },
        "countries": [
          "example"
        ]
      }
    ]
  },
  "creditsUsed": 2,
  "requestId": "a4b7b5a5-4183-4cd8-b4fb-d9fd4632efe2"
}
```

## Endpoints

| Endpoint | Cost |
| - | - |
| [Search ads in the Meta ad library](/api-reference/endpoint/meta-ads-search) | 2 credits per 10 items, at least 2 credits |
| [Get the ads a Facebook page runs](/api-reference/endpoint/meta-ads-page) | 2 credits per 10 items, at least 2 credits |
| [Get a Meta ad's details](/api-reference/endpoint/meta-ads-ad) | 2 credits |
| [Find advertisers in the Google ads library](/api-reference/endpoint/google-ads-advertisers) | 1 credit |
| [Search ads in the Google ads library](/api-reference/endpoint/google-ads-search) | 1 credit per 25 items, at least 1 credit |
| [Get a Google ad's details](/api-reference/endpoint/google-ads-ad) | 1 credit |
| [Search ads in the TikTok ad library](/api-reference/endpoint/tiktok-ads-search) | 1 credit per 12 items, at least 1 credit |
| [Get a TikTok ad's details and reach](/api-reference/endpoint/tiktok-ads-ad) | 1 credit |
| [Search ads in the LinkedIn ad library](/api-reference/endpoint/linkedin-ads-search) | 2 credits per 24 items, at least 2 credits |
| [Get a LinkedIn ad's details](/api-reference/endpoint/linkedin-ads-ad) | 2 credits |
| [Search ads in the Pinterest ads library](/api-reference/endpoint/pinterest-ads-search) | 1 credit per 24 items, at least 1 credit |
| [Get a Pinterest ad's details](/api-reference/endpoint/pinterest-ads-ad) | 1 credit |
| [Search ads in the Microsoft ads library](/api-reference/endpoint/microsoft-ads-search) | 1 credit |
| [Get a Microsoft ad's details](/api-reference/endpoint/microsoft-ads-ad) | 1 credit |
| [Find advertisers in the Microsoft ads library](/api-reference/endpoint/microsoft-ads-advertisers) | 1 credit |
| [Search ads in the Snapchat ads library](/api-reference/endpoint/snapchat-ads-search) | 1 credit per 10 items, at least 1 credit |
| [Get a Snapchat ad's details](/api-reference/endpoint/snapchat-ads-ad) | 1 credit |

## More ways to call it

### Search ads in the Google ads library

<CodeGroup>
  ```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
  import { Stophy } from "stophy";

  const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
  const result = await stophy.google.ads.search({ domain: "nike.com", limit: 25 });
  console.log(result.data.ads);
  ```

  ```python Python icon="python" theme={null}
  from stophy import Stophy

  stophy = Stophy()  # reads STOPHY_API_KEY
  result = stophy.google.ads.search(domain="nike.com", limit=25)
  print(result["data"]["ads"])
  ```

  ```bash cURL icon="terminal" theme={null}
  curl -X POST https://api.stophy.dev/v1/google/ads/search \
    -H "Authorization: Bearer $STOPHY_API_KEY" \
    -H "content-type: application/json" \
    -d '{"domain":"nike.com","limit":25}'
  ```

  ```bash CLI icon="square-terminal" theme={null}
  stophy google ads search --domain nike.com --limit 25
  ```
</CodeGroup>

### Search ads in the TikTok ad library

<CodeGroup>
  ```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
  import { Stophy } from "stophy";

  const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
  const result = await stophy.tiktok.ads.search({ query: "adidas", limit: 12 });
  console.log(result.data.ads);
  ```

  ```python Python icon="python" theme={null}
  from stophy import Stophy

  stophy = Stophy()  # reads STOPHY_API_KEY
  result = stophy.tiktok.ads.search(query="adidas", limit=12)
  print(result["data"]["ads"])
  ```

  ```bash cURL icon="terminal" theme={null}
  curl -X POST https://api.stophy.dev/v1/tiktok/ads/search \
    -H "Authorization: Bearer $STOPHY_API_KEY" \
    -H "content-type: application/json" \
    -d '{"query":"adidas","limit":12}'
  ```

  ```bash CLI icon="square-terminal" theme={null}
  stophy tiktok ads search --query adidas --limit 12
  ```
</CodeGroup>

<Tip>Every ad library needs a keyword, an advertiser, or both. See each endpoint's reference for what it accepts.</Tip>