Influencer campaign tracking

1. 1. Collect the post links

   Ask each creator for the link to every deliverable. The TikTok id is the number after /video/ in the link, and the Instagram shortcode is the code after /p/ or /reel/. TikTok's logged-out profile page does not list an account's videos, so the links are the input.

   GET /v1/tiktok/video?video_id=6718335390845095173 · video.url

   "https://www.tiktok.com/@scout2015/video/6718335390845095173"

2. 2. Snapshot TikTok posts

   The TikTok post endpoint returns views_count, likes_count, comments_count, shares_count, saves_count, and reposts_count as the post page shows them, plus the author's follower count. Large counts are the page's rounded figures, such as 159.7K, so compare growth over days rather than reading single digits.

   GET /v1/tiktok/video?video_id=6718335390845095173 · video

   {
     "video_id": "6718335390845095173",
     "url": "https://www.tiktok.com/@scout2015/video/6718335390845095173",
     "type": "video",
     "description": "Scramble up ur name & I’ll try to guess it😍❤️ #foryoupage #petsoftiktok #aesthetic",
     "published_at": "2019-07-27T13:32:38.000Z",
     "duration_ms": 10000,
     "cover": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-p-0068/2367c7d45cf54a1397abd0e72bf22eac~tplv-tiktokx-origin.image?dr=9636&x-expires=1793311200&x-signature=atz8K8hQqgXu8e4hOhmNomXtkdw%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast8",
     "images": [],
     "hashtags": [
       "foryoupage",
       "petsoftiktok",
       "aesthetic"
     ],
     "mentions": [],
     "language": "en",
     "country": "US",
     "is_ad": false,
     "ai_generated": false,
     "views_count": 159700,
     "likes_count": 35200,
     "comments_count": 5843,
     "shares_count": 1518,
     "saves_count": 649,
     "reposts_count": 0,
     "author": {
       "user_id": "53279706535428096",
       "username": "scout2015",
       "nickname": "Scout, Suki & Stella",
       "verified": true,
       "avatar": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/4cbe05e194623e3f19aef975d9fdf26c~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=7f0c927a&x-expires=1793311200&x-signature=5DMld5asM%2F1NWqWEVb5cYo6sHT0%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8",
       "url": "https://www.tiktok.com/@scout2015",
       "followers_count": 9000000,
       "likes_count": 108300000,
       "videos_count": 3079
     },
     "music": {
       "music_id": "6689804660171082501",
       "title": "original sound",
       "author": "tiff",
       "original": true,
       "duration_ms": 10000
     }
   }

3. 3. Snapshot Instagram posts

   The Instagram post endpoint returns exact likes_count and comments_count, with the newest comments. It has no play count, so a reel's views are not available; report likes and comments for Instagram and views for TikTok.

   GET /v1/instagram/post?shortcode=DeTUk4sDSp- · post.latest_comments.0

   {
     "comment_id": "18060775346647906",
     "text": "🎬🎬🎬🤹‍♀️🤹‍♀️🤹‍♀️",
     "published_at": "2026-10-28T14:20:46.000Z",
     "likes_count": 0,
     "author": {
       "user_id": "268681544",
       "username": "doctorkarin",
       "full_name": null,
       "verified": true,
       "url": "https://www.instagram.com/doctorkarin/"
     }
   }

# Daily snapshot of a campaign's posts on TikTok and Instagram.
# Appends one row per post to campaign.csv; chart it per post over time.
import csv, datetime, os, requests

API = "https://api.clair.im"
HEADERS = {"Authorization": f"Bearer {os.environ['CLAIR_API_KEY']}"}
POSTS = [  # from the creators' links: TikTok video ids, Instagram shortcodes
    ("tiktok", "6718335390845095173"),
    ("instagram", "DeTUk4sDSp-"),
]

def get(path, **params):
    r = requests.get(f"{API}{path}", headers=HEADERS, params=params, timeout=90)
    r.raise_for_status()
    return r.json()

today = datetime.date.today().isoformat()
with open("campaign.csv", "a", newline="") as f:
    out = csv.writer(f)
    for network, post_id in POSTS:
        try:
            if network == "tiktok":
                v = get("/v1/tiktok/video", video_id=post_id)["video"]
                row = [v["views_count"], v["likes_count"], v["comments_count"],
                       v["shares_count"], v["saves_count"], v["author"]["followers_count"]]
            else:
                p = get("/v1/instagram/post", shortcode=post_id)["post"]
                row = [None, p["likes_count"], p["comments_count"], None, None, None]
        except requests.HTTPError as e:
            # 404: the post was deleted or made private. Keep the row, so a
            # vanished deliverable shows up in the report.
            row = [f"http {e.response.status_code}", None, None, None, None, None]
        out.writerow([today, network, post_id, *row])

Set CLAIR_API_KEY to your Clair key; one plan covers the TikTok API and Instagram API. Each call spends that API's rate from the plan's monthly balance.

• TikTok counts are the rounded figures the post page shows, so a day's change on a large post can read as zero.
• Instagram reel plays are not returned, only likes and comments.
• Stories are not supported: they expire after a day and are not on a public page.
• A deleted or private post returns 404. Record it, since it is often the first sign a deliverable was taken down.
• There is no reach, impressions, or audience demographics. Only the creator's own account dashboards show those.