Guide

Meta Ad Library API: pull competitor ads

Meta's own Ad Library shows you ads one search at a time. If you're researching a niche, you usually want the ads alongside the organic content — same keywords, same run, one place to read both. That's what meta_ads_enabled does on a Content Research Agent.

Step 1: Create a research agent with Meta ads turned on

POST /v1/agents with meta_ads_enabled: true collects organic videos across your chosen platforms and Meta ad campaigns for the same keywords, in one job.

import requests, time

response = requests.post(
    'https://api.virlo.ai/v1/agents',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'is_recurring': False,
        'intent': 'Find what is working in Jeep Wrangler mods content right now',
        'name': 'Jeep Wrangler Mods Research',
        'keywords': ['jeep wrangler mods', 'jeep wrangler accessories', 'jeep upgrades'],
        'platforms': ['youtube', 'tiktok', 'instagram'],
        'meta_ads_enabled': True
    }
)
agent_id = response.json()['data']['id']

Step 2: Poll until it's finalized

Wait for finalized: true, not just a "completed" status — the scrape can finish while the AI analysis is still generating in the background.

while True:
    result = requests.get(
        f'https://api.virlo.ai/v1/agents/{agent_id}',
        headers={'Authorization': 'Bearer YOUR_API_KEY'}
    ).json()['data']

    if result.get('finalized'):
        break
    if result['latest_run']['status'] == 'failed':
        raise Exception('Search failed')
    # 'completed' with finalized=False just means secondary AI jobs are
    # still running — keep polling.
    time.sleep(60)

Step 3: Read the ads

Retrieval is free and unlimited once the run is finalized — slice it by any read-time filter as many times as you like.

# Meta ad campaigns running in the same niche
ads = requests.get(
    f'https://api.virlo.ai/v1/agents/{agent_id}/ads',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'limit': 50}
).json()['data']['ads']

Cost

$0.50 for the research run, covering organic content and Meta ads together. Reading the results back — as many times, with as many filters, as you want — is free.

Full reference

For every parameter, the async data model, and how to filter results, see Content Research Agents and the Async Data Model. This same call sequence is also documented as the Full Niche Analysis recipe. To run this on a schedule instead of once, see the social listening API.

Get an API key