Meta Ads

Look up Meta ads

curl --request POST \
  --url https://api.airscale.io/v1/meta-ads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain": "example.com"
}
'

const url = 'https://api.airscale.io/v1/meta-ads';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({domain: 'example.com'})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.airscale.io/v1/meta-ads"

payload = { "domain": "example.com" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "page_id": "100000000000001",
  "country_code": null,
  "continuation_token": "example-continuation-token",
  "platform": [
    "FACEBOOK",
    "INSTAGRAM"
  ],
  "media_types": "all",
  "sort_data": "SORT_BY_TOTAL_IMPRESSIONS",
  "active_status": "active",
  "is_result_complete": false,
  "number_of_ads": 4,
  "count_landing_pages": 1,
  "unique_landing_pages": [
    "https://www.example.com/"
  ],
  "start_min_date": "2026-01-01",
  "start_max_date": "2026-03-01",
  "results": [
    {
      "ad_archive_id": "200000000000001",
      "collation_id": null,
      "page_id": "100000000000001",
      "is_active": true,
      "page_name": "Example Company",
      "categories": [
        "UNKNOWN"
      ],
      "start_date": 1767225600,
      "end_date": 1772323200,
      "start_date_string": "2026-01-01",
      "end_date_string": "2026-03-01",
      "publisher_platform": [
        "FACEBOOK",
        "INSTAGRAM"
      ],
      "total_active_time": null,
      "entity_type": null,
      "url": "https://www.example.com/ads/200000000000001",
      "snapshot": {
        "page_id": "100000000000001",
        "page_profile_uri": "https://www.example.com/example-company",
        "page_name": "Example Company",
        "page_profile_picture_url": "https://www.example.com/images/example-company.png",
        "caption": "example.com",
        "title": "Example ad title",
        "body": {
          "text": "Synthetic ad text for API documentation."
        },
        "cta_text": "Learn more",
        "cta_type": "LEARN_MORE",
        "display_format": "DCO",
        "link_description": null,
        "link_url": "https://www.example.com/",
        "page_categories": [
          "Software"
        ],
        "page_like_count": 1200,
        "images": [],
        "videos": [],
        "extra_links": [],
        "extra_texts": [],
        "extra_images": [],
        "extra_videos": [],
        "current_page_name": null,
        "page_entity_type": null,
        "page_is_profile_page": null,
        "cards": [
          {
            "body": "Synthetic card text.",
            "caption": "example.com",
            "title": "Example card title",
            "cta_text": "Learn more",
            "cta_type": "LEARN_MORE",
            "link_description": null,
            "link_url": "https://www.example.com/",
            "original_image_url": "https://www.example.com/images/example-ad.png",
            "resized_image_url": "https://www.example.com/images/example-ad-small.png",
            "watermarked_resized_image_url": null,
            "video_hd_url": null,
            "video_sd_url": null,
            "video_preview_image_url": null,
            "watermarked_video_hd_url": null,
            "watermarked_video_sd_url": null,
            "image_crops": []
          }
        ]
      }
    }
  ],
  "credits_consumed": 1
}

POST

meta-ads

Look up Meta ads

curl --request POST \
  --url https://api.airscale.io/v1/meta-ads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain": "example.com"
}
'

const url = 'https://api.airscale.io/v1/meta-ads';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({domain: 'example.com'})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.airscale.io/v1/meta-ads"

payload = { "domain": "example.com" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "page_id": "100000000000001",
  "country_code": null,
  "continuation_token": "example-continuation-token",
  "platform": [
    "FACEBOOK",
    "INSTAGRAM"
  ],
  "media_types": "all",
  "sort_data": "SORT_BY_TOTAL_IMPRESSIONS",
  "active_status": "active",
  "is_result_complete": false,
  "number_of_ads": 4,
  "count_landing_pages": 1,
  "unique_landing_pages": [
    "https://www.example.com/"
  ],
  "start_min_date": "2026-01-01",
  "start_max_date": "2026-03-01",
  "results": [
    {
      "ad_archive_id": "200000000000001",
      "collation_id": null,
      "page_id": "100000000000001",
      "is_active": true,
      "page_name": "Example Company",
      "categories": [
        "UNKNOWN"
      ],
      "start_date": 1767225600,
      "end_date": 1772323200,
      "start_date_string": "2026-01-01",
      "end_date_string": "2026-03-01",
      "publisher_platform": [
        "FACEBOOK",
        "INSTAGRAM"
      ],
      "total_active_time": null,
      "entity_type": null,
      "url": "https://www.example.com/ads/200000000000001",
      "snapshot": {
        "page_id": "100000000000001",
        "page_profile_uri": "https://www.example.com/example-company",
        "page_name": "Example Company",
        "page_profile_picture_url": "https://www.example.com/images/example-company.png",
        "caption": "example.com",
        "title": "Example ad title",
        "body": {
          "text": "Synthetic ad text for API documentation."
        },
        "cta_text": "Learn more",
        "cta_type": "LEARN_MORE",
        "display_format": "DCO",
        "link_description": null,
        "link_url": "https://www.example.com/",
        "page_categories": [
          "Software"
        ],
        "page_like_count": 1200,
        "images": [],
        "videos": [],
        "extra_links": [],
        "extra_texts": [],
        "extra_images": [],
        "extra_videos": [],
        "current_page_name": null,
        "page_entity_type": null,
        "page_is_profile_page": null,
        "cards": [
          {
            "body": "Synthetic card text.",
            "caption": "example.com",
            "title": "Example card title",
            "cta_text": "Learn more",
            "cta_type": "LEARN_MORE",
            "link_description": null,
            "link_url": "https://www.example.com/",
            "original_image_url": "https://www.example.com/images/example-ad.png",
            "resized_image_url": "https://www.example.com/images/example-ad-small.png",
            "watermarked_resized_image_url": null,
            "video_hd_url": null,
            "video_sd_url": null,
            "video_preview_image_url": null,
            "watermarked_video_hd_url": null,
            "watermarked_video_sd_url": null,
            "image_crops": []
          }
        ]
      }
    }
  ],
  "credits_consumed": 1
}

Look up Meta ads for one company. Send exactly one domain field: a bare hostname or HTTP(S) URL. Paths and queries are ignored after normalization. IP literals, credentials, non-default ports, and invalid domain labels are rejected. The JSON body must fit within 16 KiB.

Usage and credits

The limit is 60 requests per minute per workspace. You need at least 1 credit before the lookup can start. A finite numeric number_of_ads greater than zero costs 1 credit. A zero, missing, nonnumeric, or nonpositive count costs 0 credits. Read credits_consumed for the cost of the lookup. Fields such as page_id and number_of_ads are optional and can vary in type; check them before use. A zero-ad result costs zero credits.

Timeouts and retries

The lookup can take up to 90 seconds. HTTP 504 means that lookup timed out without a debit. Use bounded backoff for temporary errors and rate limits. This endpoint does not support caller idempotency keys. Retrying a successful lookup can run and bill another lookup, including when the original response was lost.

Next step

Review credit balance or rate limits before scheduling more lookups.

Authorizations

Authorization

string

header

required

Use an Airscale workspace API key. Never expose the key in client-side code.

Body

application/json

domain

string

required

Bare company hostname or HTTP(S) URL. Whitespace is trimmed; hostname is lowercased and leading www. and trailing dot are removed. Paths and queries are ignored. IP literals, credentials, non-default ports, and invalid domain labels are rejected. Maximum JSON body size: 16 KiB (oversize returns 400).

Minimum string length: 1

Response

Ad lookup result and credit cost. Ad fields are optional and their types can vary.

credits_consumed

enum<integer>

required

Available options:

0,

1

page_id

any

Meta page identifier, when present.

number_of_ads

any

Ad count, when present. Only a positive finite number is billable.

country_code

any

continuation_token

any

platform

any

media_types

any

sort_data

any

active_status

any

is_result_complete

any

count_landing_pages

any

unique_landing_pages

any

start_min_date

any

start_max_date

any

results

object[]

Ads found for the page, when there are any. Ad fields vary; check for missing or null values before using them.

Show child attributes

Start here

Account

Search and discovery

Contact data

Profiles and reverse lookup

Post engagement

Miscellaneous

Usage and credits

Timeouts and retries

Next step

Authorizations

Body

Response

​Usage and credits

​Timeouts and retries

​Next step

Authorizations

Body

Response

Usage and credits

Timeouts and retries

Next step