> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creatoraudit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a weekly performance digest

> Assemble a short weekly recap from your overview stats and top movers, ready to email or post to Slack.

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.

<Note>
  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](/api-setup) or grab one from the [API keys
  page](https://app.creatoraudit.com/app/api-keys).
</Note>

<Steps>
  <Step title="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.

    ```python theme={null}
    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"]
    ```
  </Step>

  <Step title="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.

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

    ```python theme={null}
    top = client.request(
        "GET", "/creators/top", params={"period": "7d", "limit": 5}
    )
    top.raise_for_status()
    movers = top.json()["data"]
    ```
  </Step>

  <Step title="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.

    ```python theme={null}
    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()
    ```
  </Step>

  <Step title="Deliver it">
    Hand `message` to whatever you already use. Both shapes below take the same Markdown
    string — fill in your own endpoint and credentials.

    <Tabs>
      <Tab title="Chat webhook">
        ```python theme={null}
        import httpx

        httpx.post("YOUR_WEBHOOK_URL", json={"text": message}, timeout=15.0)
        ```
      </Tab>

      <Tab title="Email">
        ```python theme={null}
        # 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)
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## 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:

```cron theme={null}
0 9 * * 1  CREATORAUDIT_API_KEY=YOUR_API_KEY /usr/bin/python3 /opt/digests/weekly.py
```

<Warning>
  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](/data-freshness).
</Warning>

<Columns cols={2}>
  <Card title="Agent recipes" href="/agents/recipes">
    The same overview-plus-leaderboard pattern, framed as an agent task.
  </Card>

  <Card title="Data freshness" href="/data-freshness">
    When metrics land, and how to time scheduled jobs around it.
  </Card>

  <Card title="Analytics dashboard" href="/dashboard/analytics">
    The headline figures, rendered in the app.
  </Card>
</Columns>