API reference / Ads

Get one ad

Written and maintained by The ProspectAPIs team

GET/v1/ads/:id

GET /v1/ads/:id is the ProspectAPIs operation getAd, in the Ads group of the REST API. One ad in full by its id from GET /v1/ads, with the facts its library shows only on the single ad (for example the countries it ran in). Costs $0.006 when found; an unknown id is a free 404; a library that cannot be read is a free 503. Cost: Launching soon. Send your API key as a Bearer token in the Authorization header.

How this fits with the rest of the ads API, with worked examples, is in the ads library guide.

Parameters

Responses

Every error answers with the same JSON body, an error string and sometimes a code; the errors page lists each status and when it happens. A per-key 429 carries Retry-After; see rate limits.

200 response fields

The ad.

Code samples

Each sample sends the same request. Set PROSPECTAPIS_KEY in your environment first. Values come from the spec's examples; replace them with your own.

curl https://api.prospectapis.com/v1/ads/meta.1234567890 \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY"

const res = await fetch("https://api.prospectapis.com/v1/ads/meta.1234567890", {
  headers: { Authorization: `Bearer ${process.env.PROSPECTAPIS_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const data = await res.json();
console.log(data);

import os, requests

res = requests.get(
    "https://api.prospectapis.com/v1/ads/meta.1234567890",
    headers={"Authorization": f"Bearer {os.environ['PROSPECTAPIS_KEY']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()
print(data)

Billing

Billing reserves before it serves: the call holds what it may cost, serves at most what that hold covers, and refunds the rest when the response closes. Any non-2xx answer refunds the whole hold, so a failed call costs nothing. The response reports your balance in X-Credits-Remaining.

Related

The ads library guide covers this area end to end. Previous operation: Search a company's ads. Next operation: List queued writes. Every operation, grouped by area, is on the API reference index.

Create a free account to get a key, then run the samples above with your own values.