Skip to main content
POST
Look up Meta ads
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. The response preserves provider fields and adds credits_consumed. Fields such as page_id and number_of_ads are optional; do not assume every provider response includes them or uses a fixed type. An upstream HTTP 204 response becomes a zero-ad result.

Timeouts and retries

The provider 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 Airschool 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

Provider result with the settled credit cost. Provider fields are optional and are not coerced to fixed types.

credits_consumed
enum<integer>
required
Available options:
0,
1
page_id
any

Provider page identifier, when present.

number_of_ads
any

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