Adligator API Documentation

Getting started

The Adligator API is a RESTful HTTP API. All endpoints are served over HTTPS from the base URL below and return JSON (except the download endpoint, which responds with a redirect).

https://api.adligator.com/api/v1

1. API access requires an active Team plan.
2. Create your API key in the Developer Portal. The key is shown only once — store it securely.
3. Pass the key in the X-API-Key header with every request.

The API is currently in beta and free of charge. Limits and pricing may change once the beta ends.

Want to try without a Team plan? Use the Sandbox API key below.

Sandbox API key

Use the public sandbox key to explore the API without a Team plan or your own credentials. It searches the live ads library, restricted to the keyword "headway" and ads first seen on January 1, 2026 — so every filter, the details endpoint and media downloads behave exactly like production.

Sandbox key:

adl_sandbox000000000000000000000000000000001

How it behaves

• No Team plan required.
• The only allowed keyword is headway, passed in the body parameter. It is applied automatically when omitted; any other keyword returns empty results.
• Results are limited to ads first seen between 2026-01-01 and 2026-01-02. Date ranges outside this window return empty results.
• All other filters, pagination, sorting, ad details and media downloads work with real data.
• The same rate limits apply as for production keys.
• The sandbox key works with the REST API only; the MCP server requires a production API key.
• Facebook page search (GET /fb-pages) always returns an empty list for the sandbox key.

Example request

curl "https://api.adligator.com/api/v1/ads?body=headway&limit=5" \
  -H "X-API-Key: adl_sandbox000000000000000000000000000000001"

Replace the path with an ad id from the search response to call details or download.

Authentication

Authenticate every request with the X-API-Key header. Keys look like adl_ followed by 40 characters.

curl "https://api.adligator.com/api/v1/ads?limit=5" \
  -H "X-API-Key: adl_your_api_key_here"

Requests without a valid key are rejected:

• 401 Unauthorized — the header is missing or the key is unknown.
• 403 Forbidden — the key is deactivated or your plan does not include API access.

Rate limits

Limits are applied per API key and per endpoint. Daily counters reset at midnight UTC.

Every response includes rate limit headers:

X-RateLimit-Limit-Second: 2
X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 987

When a limit is exceeded, the API responds with 429 Too Many Requests and a Retry-After header (in seconds). Rejected requests do not count towards your daily quota.

GET Search ads

GET /api/v1/ads

Searches the ads library. Returns a paginated list with minimal ad information; use the details endpoint for media descriptors and the download endpoint for original files. All query parameters are optional. List parameters accept comma-separated values.

Query parameters

Example request

curl "https://api.adligator.com/api/v1/ads?countries=US,DE&isActive=true&title=fitness&limit=2" \
  -H "X-API-Key: adl_your_api_key_here"

Example response

{
  "data": [
    {
      "id": "9a1f4c9e-2b7d-4f1a-8c3e-5d6b7a8c9d0e",
      "isActive": true,
      "displayFormat": 1,
      "publishedOnPlatforms": ["FB", "INST"],
      "countries": ["US", "DE"],
      "countriesAmount": 2,
      "textLanguages": ["en"],
      "startDate": "2026-05-14T00:00:00.000Z",
      "endDate": null,
      "lastSeenAt": "2026-07-03T09:12:44.000Z",
      "activeDaysCount": 50,
      "copiesCount": 12,
      "title": "Get fit in 30 days",
      "linkUrl": "https://example.com/offer",
      "buttonType": "LEARN_MORE",
      "isAAAEligible": true,
      "fbPage": {
        "fbOriginalPageId": "104201234567890",
        "pageName": "Fit Life",
        "pageLikesCount": 53210,
        "profileUri": "https://facebook.com/fitlife"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "totalPages": 187
  }
}

GET Search Facebook pages

GET /api/v1/fb-pages

Looks up Facebook pages (advertisers) by name. Use it to resolve a brand, app or product name to a fbOriginalPageId before filtering ads by that advertiser. Returns the top matching candidates with page name, likes, profile link and picture.

Query parameters

Example request

curl "https://api.adligator.com/api/v1/fb-pages?query=Duolingo&limit=5" \
  -H "X-API-Key: adl_your_api_key_here"

Example response

{
  "data": [
    {
      "fbOriginalPageId": "104201234567890",
      "pageName": "Duolingo",
      "pageLikesCount": 12500000,
      "profileUri": "https://facebook.com/duolingo",
      "profilePictureUrl": "https://cdn2.adligator.com/pages/....jpg"
    }
  ],
  "totalCount": 12
}

Pass a returned fbOriginalPageId to GET /ads as fbOriginalPageId to fetch that advertiser's ads.

GET Get ad details

GET /api/v1/ads/:id

Returns full information for a single ad, including media descriptors with preview URLs. Media objects expose a mediaId that you pass to the download endpoint to retrieve the highest-resolution file.

Path parameters

Example request

curl "https://api.adligator.com/api/v1/ads/9a1f4c9e-2b7d-4f1a-8c3e-5d6b7a8c9d0e" \
  -H "X-API-Key: adl_your_api_key_here"

Example response

{
  "data": {
    "id": "9a1f4c9e-2b7d-4f1a-8c3e-5d6b7a8c9d0e",
    "isActive": true,
    "displayFormat": 1,
    "publishedOnPlatforms": ["FB", "INST"],
    "countries": ["US", "DE"],
    "title": "Get fit in 30 days",
    "linkUrl": "https://example.com/offer",
    "buttonType": "LEARN_MORE",
    "isAAAEligible": true,
    "adArchiveId": "1234567890123456",
    "categories": [0],
    "bodyHtml": "Join the challenge today...",
    "entityType": "REGULAR",
    "linkDescription": "30-day fitness challenge",
    "caption": "example.com",
    "images": [],
    "videos": [
      {
        "mediaId": "7c2e1f0a-9b8d-4e3c-a1b2-c3d4e5f60789",
        "videoUrl": "https://cdn2.adligator.com/videos/sd/....mp4",
        "previewImageUrl": "https://cdn2.adligator.com/previews/....jpg"
      }
    ],
    "cards": []
  }
}

Media URLs in this response are preview quality (resized images / SD video). Use the download endpoint to get the original file.

GET Download media

GET /api/v1/ads/:id/download?mediaId=:mediaId

Resolves the highest-resolution file (original image or HD video) for a media item of an ad and responds with 302 Found and a Location header pointing at the file. Follow the redirect to download it.

Parameters

Example request

curl -L -o creative.mp4 \
  "https://api.adligator.com/api/v1/ads/9a1f4c9e-2b7d-4f1a-8c3e-5d6b7a8c9d0e/download?mediaId=7c2e1f0a-9b8d-4e3c-a1b2-c3d4e5f60789" \
  -H "X-API-Key: adl_your_api_key_here"

Example response

HTTP/1.1 302 Found
Location: https://cdn2.adligator.com/videos/hd/....mp4

Errors

Errors use conventional HTTP status codes and a consistent JSON body:

{
  "statusCode": 401,
  "message": "Invalid API key.",
  "error": "Unauthorized"
}