Send a weekly performance digest

This tutorial builds a compact weekly digest: headline numbers from your organization overview plus the week’s top movers, formatted as Markdown your code can hand to any email or chat delivery. You’ll write the message-building part — delivery stays generic so it drops into whatever you already use.

Read fields from the live responses rather than assuming names — overview and leaderboard payloads carry the metrics you’ll quote. You’ll need an API key first — see API setup or grab one from the API keys page.

Fetch the weekly overview

GET /v2/overview returns organization-level figures for a period of 7d, 30d, or 90d. Use 7d for a week-over-week recap.

import os

import httpx

BASE_URL = "https://api.creatoraudit.com/v2"
client = httpx.Client(
    base_url=BASE_URL,
    headers={"Authorization": f"Bearer {os.environ['CREATORAUDIT_API_KEY']}"},
    timeout=30.0,
)

overview = client.request("GET", "/overview", params={"period": "7d"})
overview.raise_for_status()
summary = overview.json()["data"]

Fetch the week's top movers

GET /v2/creators/top?period=7d ranks your creators over the same window. These are the movers you’ll spotlight in the digest.

GET /v2/creators/top caps limit at 25. A handful (five or so) usually reads best in a digest.

top = client.request(
    "GET", "/creators/top", params={"period": "7d", "limit": 5}
)
top.raise_for_status()
movers = top.json()["data"]

Build the Markdown message

Assemble a short Markdown string from the two payloads. Read the metric fields off the live shapes — quote what’s actually there rather than hard-coding a structure.

def fmt_int(value) -> str:
    return f"{int(value or 0):,}"

lines = [
    "*CreatorAudit — weekly recap*",
    "",
    f"Views: {fmt_int(summary.get('views'))}  ·  "
    f"Likes: {fmt_int(summary.get('likes'))}  ·  "
    f"Followers: {fmt_int(summary.get('followers'))}",
    "",
    "*Top movers (7d)*",
]
for i, creator in enumerate(movers, start=1):
    name = creator.get("name") or creator["id"]
    views = fmt_int(creator.get("views"))
    lines.append(f"{i}. {name} — {views} views")

message = "\n".join(lines)
print(message)
client.close()

Deliver it

Hand message to whatever you already use. Both shapes below take the same Markdown string — fill in your own endpoint and credentials.

Chat webhook
Email

import httpx

httpx.post("YOUR_WEBHOOK_URL", json={"text": message}, timeout=15.0)

# Pass `message` as the body to your email provider's send call,
# rendering the Markdown to HTML first if the provider expects it.
send_email(to="team@example.com", subject="Weekly recap", body=message)

Schedule it

Run the script on a timer so the digest arrives the same time each week. A weekly cron entry — say Monday at 09:00 — is the simplest option:

0 9 * * 1  CREATORAUDIT_API_KEY=YOUR_API_KEY /usr/bin/python3 /opt/digests/weekly.py

Data is not real-time. An account or video tracked late in the window may still show last_scrape_time: null and won’t contribute to the recap until its first refresh lands. Schedule the digest a little after your accounts’ scrape cycles so the week’s numbers are settled — see Data freshness.

Agent recipes

The same overview-plus-leaderboard pattern, framed as an agent task.

Data freshness

When metrics land, and how to time scheduled jobs around it.

Analytics dashboard

The headline figures, rendered in the app.

Getting started

MCP & AI agents

Using the API

Web dashboard

Tutorials

Help

Appendix

Send a weekly performance digest

Schedule it

Agent recipes

Data freshness

Analytics dashboard

​Schedule it

Agent recipes

Data freshness

Analytics dashboard

Schedule it