curl --request GET \
--url https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"ad_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"enabled": true,
"count": 123,
"variants": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"provider": "<string>",
"platform": "<string>",
"source_ad_key": "<string>",
"status": "<string>",
"publisher_platforms": [
"<string>"
],
"source_ad_id": "<string>",
"source_ad_url": "<string>",
"display_url": "<string>",
"click_through_url": "<string>",
"landing_page_url": "<string>",
"posting_page_name": "<string>",
"advertiser_logo_url": "<string>",
"ad_format": "<string>",
"partners": [
{
"name": "<string>",
"page_id": "<string>",
"page_url": "<string>",
"profile_image_url": "<string>"
}
],
"started_running_at": "2023-11-07T05:31:56Z",
"launched_month": "<string>",
"is_top_ad": false,
"top_ad_rank": 123,
"low_impression_count": false,
"ad_has_multiple_versions": false,
"is_still_in_ad_library": true,
"last_seen_in_ad_library_at": "2023-11-07T05:31:56Z",
"last_confirmed_active_at": "2023-11-07T05:31:56Z",
"active_finished_at": "2023-11-07T05:31:56Z",
"active_duration_days": 123,
"industry": "<string>",
"first_seen_at": "2023-11-07T05:31:56Z",
"last_seen_at": "2023-11-07T05:31:56Z",
"advertiser": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"parent_company": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>"
},
"primary_domain": "<string>",
"website_url": "<string>",
"website_header_image_url": "<string>",
"industry": "<string>",
"brand_classification": {
"primary_industry": "<string>",
"industries": [
"<string>"
],
"business_models": [
"<string>"
],
"version": "<string>",
"source": "<string>",
"classified_at": "2023-11-07T05:31:56Z",
"needs_review": false
},
"filterable_industries": [
"<string>"
],
"partners": [
{
"name": "<string>",
"page_id": "<string>",
"page_url": "<string>",
"profile_image_url": "<string>"
}
]
},
"source_account": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"handle": "<string>",
"url": "<string>",
"followers": 123,
"logo_url": "<string>",
"tagline": "<string>",
"raw_data": {}
},
"creative": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"headline": "<string>",
"body_text": "<string>",
"description": "<string>",
"cta": "<string>",
"creative_type": "<string>",
"first_seen_at": "2023-11-07T05:31:56Z",
"last_seen_at": "2023-11-07T05:31:56Z",
"assets": [
{
"kind": "<string>",
"url": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url_source": "source",
"content_hash": "<string>",
"width": 123,
"height": 123,
"mime_type": "<string>",
"raw_data": {}
}
],
"media_variants": [
{
"media_url": "<string>",
"headline": "<string>",
"body_text": "<string>",
"description": "<string>",
"cta": "<string>",
"link_url": "<string>",
"display_url": "<string>"
}
],
"raw_data": {}
},
"creative_count": 0,
"variant_count": 1,
"provenance": {}
}
]
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Get Global Ad Library Ad Variants
“Creative variants” — the ad’s visual near-duplicate cluster (PR-5).
Returns the OTHER ads whose primary creative is visually near-identical
(grouped offline by cosine-threshold clustering over image embeddings). The
ad itself must exist and be visible to the caller; anything else 404s. When
the read flag (brand_intel_ad_cluster_enabled) is off, or the ad has no
image cluster, the response carries an empty list with enabled
distinguishing the two.
Brand Library tenancy applies on BOTH halves, and this route had neither. It was the only read on this router that took no user dependency at all:
- the SUBJECT probe compared
AdLibraryAd.idalone, so a 200-vs-404 answered “does this uuid exist” for any ad to any caller; - the SIBLINGS were selected by id with no predicate, and a visual cluster
deliberately spans advertisers — so opening any PUBLIC ad’s detail
returned full cards (advertiser identity, creative assets, landing URL)
for every
tenant_privatead sharing its cluster, to a caller holding no credential at all.
get_optional_user rather than get_current_user, matching every
sibling here: the global library stays browsable signed-out (ADR 0021), and
an anonymous caller simply gets the public rows.
curl --request GET \
--url https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/ad-library/ads/{ad_id}/variants")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"ad_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"enabled": true,
"count": 123,
"variants": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"provider": "<string>",
"platform": "<string>",
"source_ad_key": "<string>",
"status": "<string>",
"publisher_platforms": [
"<string>"
],
"source_ad_id": "<string>",
"source_ad_url": "<string>",
"display_url": "<string>",
"click_through_url": "<string>",
"landing_page_url": "<string>",
"posting_page_name": "<string>",
"advertiser_logo_url": "<string>",
"ad_format": "<string>",
"partners": [
{
"name": "<string>",
"page_id": "<string>",
"page_url": "<string>",
"profile_image_url": "<string>"
}
],
"started_running_at": "2023-11-07T05:31:56Z",
"launched_month": "<string>",
"is_top_ad": false,
"top_ad_rank": 123,
"low_impression_count": false,
"ad_has_multiple_versions": false,
"is_still_in_ad_library": true,
"last_seen_in_ad_library_at": "2023-11-07T05:31:56Z",
"last_confirmed_active_at": "2023-11-07T05:31:56Z",
"active_finished_at": "2023-11-07T05:31:56Z",
"active_duration_days": 123,
"industry": "<string>",
"first_seen_at": "2023-11-07T05:31:56Z",
"last_seen_at": "2023-11-07T05:31:56Z",
"advertiser": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"parent_company": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>"
},
"primary_domain": "<string>",
"website_url": "<string>",
"website_header_image_url": "<string>",
"industry": "<string>",
"brand_classification": {
"primary_industry": "<string>",
"industries": [
"<string>"
],
"business_models": [
"<string>"
],
"version": "<string>",
"source": "<string>",
"classified_at": "2023-11-07T05:31:56Z",
"needs_review": false
},
"filterable_industries": [
"<string>"
],
"partners": [
{
"name": "<string>",
"page_id": "<string>",
"page_url": "<string>",
"profile_image_url": "<string>"
}
]
},
"source_account": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"handle": "<string>",
"url": "<string>",
"followers": 123,
"logo_url": "<string>",
"tagline": "<string>",
"raw_data": {}
},
"creative": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"headline": "<string>",
"body_text": "<string>",
"description": "<string>",
"cta": "<string>",
"creative_type": "<string>",
"first_seen_at": "2023-11-07T05:31:56Z",
"last_seen_at": "2023-11-07T05:31:56Z",
"assets": [
{
"kind": "<string>",
"url": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url_source": "source",
"content_hash": "<string>",
"width": 123,
"height": 123,
"mime_type": "<string>",
"raw_data": {}
}
],
"media_variants": [
{
"media_url": "<string>",
"headline": "<string>",
"body_text": "<string>",
"description": "<string>",
"cta": "<string>",
"link_url": "<string>",
"display_url": "<string>"
}
],
"raw_data": {}
},
"creative_count": 0,
"variant_count": 1,
"provenance": {}
}
]
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Query Parameters
1 <= x <= 60Response
Successful Response
"Creative variants" for one ad — its visual near-duplicate cluster (PR-5).
variants are the OTHER ads whose primary creative is visually
near-identical to ad_id's (same image reused across advertisers, or a
lightly-edited variant), grouped offline by cosine-threshold clustering over
image embeddings. Empty variants (the common case) means the ad has no
visual duplicate, or the read flag is off — the client renders "no variants"
either way. enabled distinguishes the two for UI copy.
Was this page helpful?