Competitor Research

Find a competitor brand and collect its active video ads for creative research.

Before you start

Install requests and set ATRIA_API_KEY to your API key.
Choose the competitor you want to research.
Following a brand changes your workspace's followed list and uses its follow quota.

Workflow

Step	Request	What to use next
Find the brand	`POST /open/v1/inspo-brands/search`	Select the matching `data.items[].id`.
Check its profile	`GET /open/v1/inspo-brands/{brand_id}`	Confirm its name and primary host.
Follow it	`POST /open/v1/inspo-brands/follow`	Use the returned brand `id`.
Retrieve ads	`GET /open/v1/ad-library/search`	Pass `unified_brand_id` and follow the response cursor.

Find the brand

Replace Acme with the competitor's name:

curl -sS -X POST \
  -H "X-API-Key: $ATRIA_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"scope":"library","library":{"brand_name":"Acme","limit":5}}' \
  "https://api.tryatria.com/open/v1/inspo-brands/search"

Choose the correct result and set ATRIA_INSPO_BRAND_ID to its id.

Follow and retrieve ads

Run this after selecting the intended brand. It confirms the profile, follows the brand, and prints every page of active video ads.

import os
from uuid import UUID

import requests

BASE = "https://api.tryatria.com/open/v1"
HEADERS = {"X-API-Key": os.environ["ATRIA_API_KEY"]}


def call(method, path, **kwargs):
    response = requests.request(
        method,
        BASE + path,
        headers=HEADERS,
        timeout=30,
        **kwargs,
    )
    response.raise_for_status()
    payload = response.json()
    if payload.get("code") != 0:
        raise RuntimeError(
            f"API error {payload.get('code')}: {payload.get('message')}"
        )
    return payload["data"]


brand_id = str(UUID(os.environ["ATRIA_INSPO_BRAND_ID"]))
brand = call("GET", f"/inspo-brands/{brand_id}")
print("Brand:", brand.get("name"), brand.get("primary_host"))

follow = call(
    "POST",
    "/inspo-brands/follow",
    json={"brand_id": str(UUID(brand["id"]))},
)
print("Follow quota:", follow["quota"])

params = {
    "unified_brand_id": str(UUID(follow["id"])),
    "status": "active",
    "display_format": "video",
    "order": "newest",
    "page_size": 20,
}
while True:
    page = call("GET", "/ad-library/search", params=params)
    for ad in page["items"]:
        print(ad["id"], ad.get("brand_name") or "", ad.get("title") or "")

    cursor = page.get("cursor")
    if not cursor:
        break
    params["cursor"] = cursor

Notes

Use the brand UUID from search/follow for unified_brand_id. An ad's brand_id is an advertiser ID.
Results use the workspace's tracked coverage for that brand. Empty coverage returns no ads.
Keep filters unchanged while paging. Reset the cursor when changing the brand or filters.
To unfollow, POST {"brand_id":"<brand UUID>"} to /open/v1/inspo-brands/unfollow. Do not automatically undo an existing follow.