AdLibrary API Documentation & Integration Guide

AdLibrary API Endpoint

The AdLibrary API lets you programmatically search ads across Facebook, Instagram, TikTok, Google and more. All requests go through a single base URL:

1https://adlibrary.com/api/search

The API accepts both POST and GET requests. We recommend POST for complex queries with filters.

Authentication

The API uses API key authentication. Include your key in the Authorization header with every request:

1Authorization: Bearer adl_your_api_key

• Business subscription required — API access is only available on the Business plan

• API keys are prefixed with adl_ and managed in your developer dashboard

• 1 credit per request — credits are deducted from your account balance

• Rate limits: 10 requests/minute, 10,000 requests/day

Getting Your API Key

Log into adlibrary.com, navigate to your developer settings, and create a new API key. Each key is shown once at creation — store it securely. You can revoke and create new keys at any time.

Pricing

Each API request costs 1 credit, the same as a GUI search. Every response includes a _credits object showing your remaining balance:

1{
2  "_credits": {
3    "used": 1,
4    "remaining": 999,
5    "autoCharged": false,
6    "creditsAdded": 0
7  }
8}

Search Endpoint

The primary endpoint for searching ads across all supported platforms.

1curl -X POST "https://adlibrary.com/api/search" \
2  -H "Authorization: Bearer adl_your_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "keyword": "fitness app",
6    "appType": "2",
7    "geo": ["USA"],
8    "adsType": ["2"],
9    "daysBack": 30,
10    "pageSize": 10
11  }'

Required Parameters

Parameter	Type	Description
`keyword`	`string`	Search term to find ads
`appType`	`string`	Category: `"1"` = Gaming, `"2"` = Apps, `"3"` = E-commerce

Optional Parameters

Pagination

Parameter	Type	Default	Description
`page`	`number`	`1`	Page number
`pageSize`	`number`	`20`	Results per page (max 50)

Filters

Parameter	Type	Description
`geo`	`string[]`	ISO 3-letter country codes, e.g. `["USA", "GBR", "DEU"]`
`language`	`string[]`	Language codes, e.g. `["en"]`
`platform`	`string[]`	`"facebook"`, `"instagram"`, `"tiktok"`, etc.
`adsType`	`string[]`	`"1"` = image, `"2"` = video, `"3"` = carousel

Date Range

Parameter	Type	Description
`daysBack`	`number`	Ads from last N days
`dateFrom`	`string`	ISO date start, e.g. `"2024-01-01"`
`dateTo`	`string`	ISO date end, e.g. `"2024-01-31"`

Engagement Filters

Parameter	Type	Description
`likeBegin`	`number`	Minimum likes
`likeEnd`	`number`	Maximum likes

Sorting

Parameter	Type	Options
`sortField`	`string`	`"like"`, `"share"`, `"comment"`, `"impression"`, `"time"`

Search Response

json

{
  "list": [
    {
      "ad_key": "abc123",
      "title": "Ad headline",
      "body": "Ad body text",
      "advertiser_name": "Brand Name",
      "platform": "facebook",
      "preview_img_url": "https://...",
      "like_count": 1234,
      "share_count": 567,
      "impression": 50000,
      "geo": ["USA", "GBR"],
      "first_seen": "2024-01-15",
      "last_seen": "2024-01-20"
    }
  ],
  "total": 1500,
  "page": 1,
  "pageSize": 20,
  "_credits": { "used": 1, "remaining": 999 }
}

Enrichment Endpoint

POST /api/enrichment — 1 credit (cached 30 days)

Get AI-powered analysis of any ad: hook, angle, target audience, emotional triggers, and swipe-file insights.

Request

json

{
  "ad": {
    "ad_key": "abc123",
    "platform": "facebook",
    "title": "Ad headline",
    "body": "Ad body text",
    "advertiser_name": "Brand",
    "preview_img_url": "https://...",
    "like_count": 1234,
    "impression": 50000
  }
}

Response

json

{
  "hook": "Problem-agitate pattern",
  "angle": "Fear of missing out",
  "targetAudience": "Health-conscious millennials",
  "emotionalTriggers": ["FOMO", "Social proof"],
  "swipeFile": [
    "Question headline format",
    "Before/after visual structure"
  ],
  "_credits": { "used": 1, "remaining": 998 }
}

Error Codes

Code	Description	Solution
`401`	Invalid or missing API key	Check your `Authorization` header
`402`	Insufficient credits	Purchase more credits
`403`	API access requires Business plan	Upgrade your subscription
`429`	Rate limit exceeded	Check `Retry-After` header and slow down

Rate Limits

Limit	Value
Per minute	10 requests
Per day	10,000 requests
Per request cost	1 credit

When you exceed the rate limit, the API responds with HTTP 429 and includes a Retry-After header indicating how many seconds to wait.

Integration Examples

Node.js / JavaScript

javascript

const searchAds = async (keyword, options = {}) => {
  const response = await fetch('https://adlibrary.com/api/search', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer adl_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      keyword,
      appType: options.appType || '2',
      geo: options.geo || ['USA'],
      pageSize: options.pageSize || 20,
      daysBack: options.daysBack || 30,
      ...options
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error ${response.status}: ${error.error}`);
  }

  return response.json();
};

// Usage
const results = await searchAds('fitness app', {
  geo: ['USA', 'GBR'],
  adsType: ['2'],
  pageSize: 10
});

console.log(`Found ${results.total} ads, ${results._credits.remaining} credits left`);

Python

python

import requests

class AdLibraryAPI:
    def __init__(self, api_key):
        self.base_url = 'https://adlibrary.com/api'
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

    def search(self, keyword, app_type='2', **kwargs):
        payload = {
            'keyword': keyword,
            'appType': app_type,
            **kwargs
        }

        response = requests.post(
            f'{self.base_url}/search',
            headers=self.headers,
            json=payload
        )

        if response.status_code != 200:
            error = response.json()
            raise Exception(f"API Error: {error.get('error', 'Unknown')}")

        return response.json()

    def enrich(self, ad_data):
        response = requests.post(
            f'{self.base_url}/enrichment',
            headers=self.headers,
            json={'ad': ad_data}
        )
        return response.json()


# Usage
api = AdLibraryAPI('adl_your_api_key')

results = api.search(
    'sustainable fashion',
    geo=['USA', 'DEU'],
    adsType=['2'],
    daysBack=30,
    pageSize=10
)

print(f"Found {results['total']} ads")

# Enrich the first result
if results['list']:
    enriched = api.enrich(results['list'][0])
    print(f"Hook: {enriched['hook']}")
    print(f"Target: {enriched['targetAudience']}")

cURL

bash

# Search for video ads about fitness in the US
curl -X POST "https://adlibrary.com/api/search" \
  -H "Authorization: Bearer adl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "fitness app",
    "appType": "2",
    "geo": ["USA"],
    "adsType": ["2"],
    "daysBack": 30,
    "pageSize": 10
  }'

# Enrich a specific ad
curl -X POST "https://adlibrary.com/api/enrichment" \
  -H "Authorization: Bearer adl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ad": {
      "ad_key": "abc123",
      "platform": "facebook",
      "title": "Get Fit in 30 Days",
      "body": "Transform your body with our AI-powered fitness plan"
    }
  }'

Full adlibrary API Documentation and Implementation Guide

Sections

AdLibrary API Endpoint

Authentication

Getting Your API Key

Pricing

Search Endpoint

Required Parameters

Optional Parameters

Filters

Date Range

Engagement Filters

Sorting

Search Response

Enrichment Endpoint

Request

Response

Error Codes

Rate Limits

Integration Examples

Node.js / JavaScript

Python

cURL