API Documentation

Introduction

The Metapi API provides programmatic access to the Facebook Ad Library. Search ads by keyword, advertiser, or country. Retrieve ad creatives, spend data, targeting details, and more. The API returns structured JSON (or CSV) responses and supports real-time webhook notifications.

All endpoints are RESTful, use standard HTTP methods, and return consistent response envelopes. Authentication is handled via Bearer tokens in the Authorization header.

Quick Start

Make your first API call in seconds. Replace YOUR_API_KEY with the key from your dashboard.

curl -X POST "https://api.metapi.io/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "shopify", "country": "US"}'

Authentication

All API requests require a valid API key sent as a Bearer token in the Authorization header. Requests without a valid key will receive a 401 Unauthorized response.

How to get an API key

1. Sign up for a Metapi account at metapi.io
2. Navigate to the API Keys section in your dashboard
3. Click "Create New Key" and give it a descriptive name
4. Copy the key immediately -- it will only be shown once

Example Header

Authorization: Bearer mk_live_abc123def456ghi789jkl012mno345

Security Best Practices

• Store your API key in environment variables, never hard-code it in source files
• Never expose your API key in client-side JavaScript or public repositories
• Rotate your keys periodically and revoke any compromised keys immediately
• Use separate API keys for development and production environments

Base URL

All API requests are made to the following base URL. Every endpoint described in this documentation is relative to this base.

https://api.metapi.io/v1

• HTTPS required -- all requests must use HTTPS. Plain HTTP requests will be rejected.
• JSON content type -- set Content-Type: application/json for all requests with a body.
• Versioning -- the current version is v1. Breaking changes will be introduced in a new version. The v1 namespace will remain stable.

Create a new scraping task. Performs a keyword search or advertiser search depending on the parameters provided. Returns a task ID that you can poll for progress and results.

Field Reference

Request Examples

Keyword search — find ads matching a query:

curl -X POST "https://api.metapi.io/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "shopify",
    "country": "US",
    "count": 100,
    "sort_data": {
      "mode": "relevancy_monthly_grouped",
      "direction": "desc"
    }
  }'

Advertiser search — get all ads from a specific Facebook page (no q needed):

curl -X POST "https://api.metapi.io/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiser_id": "946786242013194",
    "count": 500
  }'

Response Example

{
  "task_id": "abc123",
  "status": "running",
  "message": "Task created. Poll GET /v1/tasks/abc123/status for progress."
}

Check the status and progress of a task. Returns real-time progress information including parsed items count and completion percentage.

Field Reference

Response Fields

Request Example

curl -X GET "https://api.metapi.io/v1/tasks/abc123/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "task_id": "abc123",
  "status": "running",
  "results_count": 47,
  "progress_percent": 47,
  "items_parsed": 47,
  "stage": "scraping",
  "started_at": "2026-02-20T10:30:00Z",
  "finished_at": null,
  "duration_seconds": null,
  "error_message": null
}

Retrieve the ads collected by a task. Available when the task has reached a terminal status (succeeded, failed, timed_out, or aborted). Returns a paginated list of ad objects in Tyver flat format (see Ad Object Reference). Use Task Status to check when results are ready.

Path and query parameters

Response

Same structure as Response Format: data is an array of ad objects (each matches the Ad Object Reference), and pagination contains total, offset, limit, and has_more.

Request Example

curl -X GET "https://api.metapi.io/v1/tasks/abc123/results?offset=0&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "data": [
    {
      "provider_id": 669937005838022,
      "provider_page_id": "1765633470373416",
      "provider_page_name": "MINISO",
      "cta_text": "Like Page",
      "bodies": ["Pink petals, soft smiles, and spring in full swing."],
      "captions": ["miniso.com"],
      "original_image_url": "https://scontent-dfw5-1.xx.fbcdn.net/v/...",
      "creation_time": "2025-10-20",
      "delivery_start_time": "2025-10-20",
      "delivery_stop_time": "2026-02-03"
    }
  ],
  "pagination": {
    "total": 150,
    "offset": 0,
    "limit": 10,
    "has_more": true
  }
}

Each item in data is a full ad object in Tyver format; only a subset of fields is shown above. See Ad Object Reference for all fields.

Stop a running task. Returns 409 Conflict if the task has already finished. Partial results collected before stopping are preserved.

Field Reference

Request Example

curl -X POST "https://api.metapi.io/v1/tasks/abc123/stop" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

{
  "task_id": "abc123",
  "status": "aborted",
  "message": "Task stopped successfully."
}

{
  "error": {
    "code": "conflict",
    "message": "Task is already finished"
  }
}

Create a new webhook subscription. When matching events occur, Metapi will send an HTTP POST request to your specified URL with the event payload.

Request Body Field Reference

Request Example

curl -X POST "https://api.metapi.io/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/metapi",
    "events": ["run.completed", "run.failed"],
    "filters": {
      "country": "US",
      "advertiser_id": "946786242013194",
      "keyword": "shopify"
    },
    "signing_secret": "whsec_your_signing_secret_here"
  }'

Response Example

{
  "data": {
    "webhook_id": "wh_abc123def456",
    "url": "https://your-app.com/webhooks/metapi",
    "events": ["run.completed", "run.failed"],
    "filters": {
      "country": "US",
      "advertiser_id": "946786242013194",
      "keyword": "shopify"
    },
    "signing_secret": "whsec_your_signing_secret_here",
    "active": true,
    "created_at": "2025-06-15T10:30:00Z"
  }
}

List all webhook subscriptions for your account. Returns an array of webhook objects with their current configuration and status.

Request Example

curl -X GET "https://api.metapi.io/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

{
  "data": [
    {
      "webhook_id": "wh_abc123def456",
      "url": "https://your-app.com/webhooks/metapi",
      "events": ["run.completed", "run.failed"],
      "filters": {
        "country": "US",
        "advertiser_id": "946786242013194",
        "keyword": "shopify"
      },
      "active": true,
      "created_at": "2025-06-15T10:30:00Z",
      "last_triggered_at": "2025-10-14T08:22:15Z"
    },
    {
      "webhook_id": "wh_xyz789ghi012",
      "url": "https://your-app.com/webhooks/competitor-alerts",
      "events": ["run.completed", "run.progress"],
      "filters": {
        "country": "DE",
        "keyword": "saas"
      },
      "active": true,
      "created_at": "2025-07-20T14:00:00Z",
      "last_triggered_at": "2025-10-13T19:45:30Z"
    }
  ]
}

Delete a webhook subscription. The webhook will stop receiving events immediately. This action cannot be undone.

Field Reference

Request Example

curl -X DELETE "https://api.metapi.io/v1/webhooks/wh_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns 204 No Content on success with an empty response body.

Webhook Events

Metapi sends webhook events when the status of your search tasks changes. Subscribe to one or more event types when creating a webhook.

Event Types

Signature Verification

Every webhook request includes an X-Metapi-Signature header containing the raw hex digest of an HMAC-SHA256 signature of the request body (no sha256= prefix). The header is signed with your signing_secret. If you did not provide one when creating the webhook, Metapi generated it for you. Always verify this signature before processing the payload.

# Verify the webhook signature (header value is raw hex, no sha256= prefix)
import hmac
import hashlib

def verify_signature(payload_body, signature_header, secret):
    # payload_body: raw request body as bytes; signature_header: X-Metapi-Signature value (hex string)
    if isinstance(payload_body, str):
        payload_body = payload_body.encode("utf-8")
    expected = hmac.new(
        secret.encode("utf-8"),
        payload_body,
        digestmod=hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Delivery Headers

Each delivery sends only these headers. No X-Metapi-Delivery or other delivery-ID header is sent.

Webhook Payload Example

// Headers
Content-Type: application/json
X-Metapi-Signature: a1b2c3d4e5f6...
X-Metapi-Event: run.completed
X-Metapi-Timestamp: 1740700200

// Body
{
  "event": "run.completed",
  "run_id": "abc123def456ghij",
  "status": "succeeded",
  "results_count": 150,
  "finished_at": "2026-02-28T12:00:00Z"
}

Response Format

All list endpoints return responses in a standard envelope format with offset-based pagination. The response has a data array and a pagination object.

Envelope Fields

Example

{
  "data": [
    // ... result objects
  ],
  "pagination": {
    "total": 4328,
    "offset": 0,
    "limit": 100,
    "has_more": true
  }
}

Ad Object Reference

Ad objects are returned in Tyver flat format: a single-level structure with no nested snapshot. Each field may be null if not provided by the parser. Below is the full field reference.

Ad Object Fields

Pagination

The Metapi API uses offset-based pagination. List endpoints accept offset and limit and return a data array plus a pagination object with total, offset, limit, and has_more.

Request Parameters

Response Fields

Pagination metadata is returned inside the pagination object (see Response Format).

Python Task Polling Example

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.metapi.io/v1"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Create a task with a large count
response = requests.post(
    f"{BASE_URL}/tasks",
    headers=headers,
    json={
        "q": "shopify",
        "country": "US",
        "count": 50000
    }
)
task_id = response.json()["task_id"]

# Poll until the task finishes
while True:
    status = requests.get(
        f"{BASE_URL}/tasks/{task_id}/status",
        headers=headers
    ).json()

    print(f"Progress: {status['progress_percent']}% ({status['items_parsed']} items)")

    if status["status"] in ("succeeded", "failed", "timed_out", "aborted"):
        break
    time.sleep(2)

print(f"Fetched {status['results_count']} ads in total")

Error Codes

The Metapi API uses standard HTTP status codes to indicate the success or failure of a request. Error responses include a JSON body with a code and message for debugging.

HTTP Status Codes

Error Response Format

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Rate Limits

Rate limits are applied per API key and vary by plan tier. All responses include rate limit headers so you can track your usage in real time.

Limits by Plan

Record Limits

In addition to request rate limits, each plan has a monthly cap on the total number of records your account can retrieve. A record is one ad object returned in task results. Record limits reset at the start of each billing cycle (monthly).

* Free plan has a hard block at its record limit -- requests are rejected once the cap is reached. Upgrade to a paid plan for overage billing.

** Paid plans (Lite through Scale) allow overage beyond the monthly cap. Overage rates: Lite $1.00/1K, Pro $0.80/1K, Business $0.30/1K, Scale $0.15/1K records.

402 Quota Exceeded Response

When your account exceeds its record limit, the API returns a 402 response with the quota_exceeded error code. The message includes your current usage and limit.

{
  "error": {
    "code": "quota_exceeded",
    "message": "You have exceeded your plan's record limit (3,200/3,000). Please upgrade your plan."
  }
}

Rate Limit Headers

Every API response includes the following headers to help you manage your request rate.

429 Response Example

// Response Headers
X-RateLimit-Limit-Minute: 120
X-RateLimit-Remaining-Minute: 0
X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 432
Retry-After: 45

// Response Body
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Please retry after 45 seconds."
  }
}

cURL Examples

Quick command-line examples using cURL. Replace YOUR_API_KEY with your actual API key.

Create a Keyword Search Task

# Create a keyword search task for Shopify ads in the US
curl -X POST "https://api.metapi.io/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "shopify", "country": "US", "count": 100, "sort_data": {"mode": "relevancy_monthly_grouped", "direction": "desc"}}'

Create an Advertiser Search Task

# Create an advertiser search task by page ID
curl -X POST "https://api.metapi.io/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id": "946786242013194", "country": "US"}'

Check Task Status

# Check the status of a running task
curl -X GET "https://api.metapi.io/v1/tasks/abc123/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Stop a Running Task

# Stop a running task
curl -X POST "https://api.metapi.io/v1/tasks/abc123/stop" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python Examples

Examples using the requests library. Install it with pip install requests.

Create Task and Poll for Results

import os
import requests
import time

API_KEY = os.environ["METAPI_API_KEY"]
BASE_URL = "https://api.metapi.io/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Create a keyword search task
response = requests.post(
    f"{BASE_URL}/tasks",
    headers=headers,
    json={
        "q": "shopify",
        "country": "US",
        "count": 100,
        "sort_data": {
            "mode": "total_impressions",
            "direction": "desc"
        }
    }
)

task = response.json()
task_id = task["task_id"]
print(f"Task created: {task_id}")

# Poll for task completion
while True:
    status_response = requests.get(
        f"{BASE_URL}/tasks/{task_id}/status",
        headers=headers
    )
    status = status_response.json()
    print(f"  Status: {status['status']} - {status['progress_percent']}% ({status['items_parsed']} items)")

    if status["status"] in ("succeeded", "failed", "timed_out", "aborted"):
        break

    time.sleep(2)

print(f"Task finished with {status['results_count']} results")

Advertiser Search

import os
import requests
import time

API_KEY = os.environ["METAPI_API_KEY"]
BASE_URL = "https://api.metapi.io/v1"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def create_and_wait(payload, poll_interval=2):
    """Create a task and wait for it to complete."""
    # Create the task
    response = requests.post(f"{BASE_URL}/tasks", headers=headers, json=payload)
    response.raise_for_status()
    task_id = response.json()["task_id"]
    print(f"Task created: {task_id}")

    # Poll until finished
    while True:
        status = requests.get(f"{BASE_URL}/tasks/{task_id}/status", headers=headers).json()
        print(f"  {status['status']} - {status['progress_percent']}%")

        if status["status"] in ("succeeded", "failed", "timed_out", "aborted"):
            return status

        time.sleep(poll_interval)

# Usage: search by advertiser page ID
result = create_and_wait({
    "advertiser_id": "946786242013194",
    "country": "US",
    "count": 500
})
print(f"Total results: {result['results_count']}")

Error Handling

import os
import requests
import time

API_KEY = os.environ["METAPI_API_KEY"]
BASE_URL = "https://api.metapi.io/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

def make_request(url, params=None, max_retries=3):
    """Make an API request with retry logic and error handling."""
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers, params=params)

            if response.status_code == 200:
                return response.json()

            elif response.status_code == 429:
                # Rate limited - wait and retry
                retry_after = int(response.headers.get("Retry-After", 60))
                print(f"Rate limited. Retrying in {retry_after}s...")
                time.sleep(retry_after)
                continue

            elif response.status_code == 401:
                raise Exception("Invalid API key. Check your METAPI_API_KEY.")

            elif response.status_code >= 500:
                # Server error - retry with backoff
                wait = 2 ** attempt
                print(f"Server error {response.status_code}. Retrying in {wait}s...")
                time.sleep(wait)
                continue

            else:
                error = response.json().get("error", {})
                raise Exception(f"API error: {error.get('message', 'Unknown error')}")

        except requests.exceptions.ConnectionError:
            wait = 2 ** attempt
            print(f"Connection failed. Retrying in {wait}s...")
            time.sleep(wait)

    raise Exception(f"Failed after {max_retries} retries")

# Usage
data = make_request(f"{BASE_URL}/tasks/{task_id}/status")
print(f"Found {data['results_count']} ads")