Skip to main content
POST
Look up Google ads
Look up Google 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 2 requests per rolling second and 120 requests per rolling minute per workspace. You need at least 1 credit before a lookup can start. A valid result with a positive total_ad_count or a nonempty ads array costs 1 credit. A valid zero-ad result costs 0 credits. Read credits_consumed for the charge. The endpoint returns the first page of up to 20 ads. total_ad_count can be larger than the returned ads array. If next_page_token is present, it is returned, but this endpoint does not accept a token or fetch later pages. The response is a JSON object. Common fields are status, country_code, total_ad_count (often a numeric string), available_ads_in_response, ads, cached, and credits_consumed. Each ad can include advertiser_id, advertiser_name, creative_id, original_url, start, last_seen, format_type, and a variants array with creative content or image URLs. Fields may be absent or vary by ad format. Treat any HTML in variants[].content as untrusted.

Errors and retries

Invalid input returns 400; insufficient credits returns 403; the workspace limit returns 429. Lookup failures return 502, configuration or settlement failures return 503, and lookup timeouts return 504. Failed lookups and valid zero-ad results do not consume credits. There is no caller idempotency key. A retry can run another lookup and charge another credit if ads are found. A 503 after a completed lookup can mean credit settlement is uncertain; check your balance or contact support before retrying.

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

First-page ad lookup result and credit cost. Additional fields may be present.

credits_consumed
enum<integer>
required
Available options:
0,
1
status
string

Lookup status, when supplied.

country_code
string

Country code used for the returned ads, when supplied.

total_ad_count

Total matching ads. Often returned as a numeric string and can exceed the number of ads in this response.

Pattern: ^\d+$
available_ads_in_response
integer

Number of ads available in this response, when supplied.

Required range: x >= 0
ads
object[]

First page of up to 20 ads. Fields can vary by ad format.

cached
boolean

Whether the lookup result was cached, when supplied.

next_page_token
string

Continuation token, when present. This endpoint does not fetch another page.