zelf.developers

Analytics

Compare a brand against its competitors: totals per brand and follower history over time. Every endpoint takes the same brand, platform and date window.

Compare Brand Performance

GET/api/v1/analytics/brand_comparison/analytics.brand_comparison

Returns one row of totals per brand: the top-level brand named by brand_id first, then each of its competitor sub-brands by title. Theme sub-brands are not competitors and are left out. The statistics block has the same shape as content.statistics, so the same parsing works for both. It counts the same window, and it leaves out mentions that appear only in a comment, which content.statistics includes.

brand_id must name a top-level brand. A sub-brand is refused with the id of the parent to use instead.

Parameters

brand_idType: stringRequired

The top-level brand to analyse, as returned by brands.list. A sub-brand is refused with the id of the parent to use instead.

platformType: enum[]unique items true

Platforms to include, comma-separated. Defaults to all of them.

Show values
unique items
true
instagramtiktokyoutube
posted_afterType: string(date-time)

Start of the window (UTC, ISO 8601). Supplying more than one start is accepted and only one applies: this one wins over posted_within_hours, which wins over posted_within_days.

posted_beforeType: string(date-time)

End of the window (UTC, ISO 8601). Defaults to the current time, and a relative start is counted back from it.

posted_within_hoursType: integerminimum 1 · maximum 8760

Start of the window, counted back from posted_before or the current time, in hours (1-8760). posted_after wins over it; it wins over posted_within_days.

minimum
1
maximum
8760
posted_within_daysType: integerminimum 1 · maximum 365

Start of the window, counted back from posted_before or the current time, in days (1-365). Defaults to 7 when no date parameter is supplied, and loses to posted_after and posted_within_hours.

minimum
1
maximum
365

Returns BrandComparison

brandType: AnalyticsBrand

The brand this row covers.

Show child attributes
brand.idType: stringread-only

Unique identifier for the brand.

brand.titleType: stringor null

Display name of the brand.

brand.is_primaryType: boolean

true for the brand the request named, false for a sub-brand.

brand.sub_brand_typeType: stringor nullread-only

COMPETITIVE or THEME for a sub-brand; null for the top-level brand the request named.

statisticsType: BrandStatistics

Totals over the window.

Show child attributes
statistics.post_countType: integer

Number of posts matched to the brand.

statistics.total_viewsType: integer

Total views across those posts.

statistics.total_likesType: integer

Total likes across those posts.

statistics.total_commentsType: integer

Total comments across those posts.

statistics.total_sharesType: integer

Total shares across those posts.

statistics.total_engagementType: integer

Likes, comments and shares across those posts.

statistics.total_earned_media_value_centsType: integer

Estimated marketing value across those posts, in US cents.

statistics.engagement_rateType: number(double)or null

Total engagement divided by total views. Null when the set has no recorded views.

statistics.unique_creator_countType: integer

Number of distinct creators who posted.

statistics.total_positive_npsType: integer

Engagement on positive posts.

statistics.total_neutral_npsType: integer

Engagement on neutral posts.

statistics.total_negative_npsType: integer

Engagement on negative posts.

followersType: BrandFollowers

Follower counts as they stand now, not over the window.

Show child attributes
followers.totalType: integer

Followers across every owned handle.

followers.accountsType: FollowerAccount[]

Per handle counts that add up to total.

Show child attributes
followers.accounts[].platformType: string

The platform the handle is on.

followers.accounts[].usernameType: string

The handle.

followers.accounts[].followersType: integer

Follower count for this handle.

Responses

BrandComparison

brandType: AnalyticsBrand

The brand this row covers.

Show child attributes
brand.idType: stringread-only

Unique identifier for the brand.

brand.titleType: stringor null

Display name of the brand.

brand.is_primaryType: boolean

true for the brand the request named, false for a sub-brand.

brand.sub_brand_typeType: stringor nullread-only

COMPETITIVE or THEME for a sub-brand; null for the top-level brand the request named.

statisticsType: BrandStatistics

Totals over the window.

Show child attributes
statistics.post_countType: integer

Number of posts matched to the brand.

statistics.total_viewsType: integer

Total views across those posts.

statistics.total_likesType: integer

Total likes across those posts.

statistics.total_commentsType: integer

Total comments across those posts.

statistics.total_sharesType: integer

Total shares across those posts.

statistics.total_engagementType: integer

Likes, comments and shares across those posts.

statistics.total_earned_media_value_centsType: integer

Estimated marketing value across those posts, in US cents.

statistics.engagement_rateType: number(double)or null

Total engagement divided by total views. Null when the set has no recorded views.

statistics.unique_creator_countType: integer

Number of distinct creators who posted.

statistics.total_positive_npsType: integer

Engagement on positive posts.

statistics.total_neutral_npsType: integer

Engagement on neutral posts.

statistics.total_negative_npsType: integer

Engagement on negative posts.

followersType: BrandFollowers

Follower counts as they stand now, not over the window.

Show child attributes
followers.totalType: integer

Followers across every owned handle.

followers.accountsType: FollowerAccount[]

Per handle counts that add up to total.

Show child attributes
followers.accounts[].platformType: string

The platform the handle is on.

followers.accounts[].usernameType: string

The handle.

followers.accounts[].followersType: integer

Follower count for this handle.

Request

stringRequired
platformenum[]
string(date-time)
from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key="<your-api-key>")

result = client.analytics.brand_comparison()
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "brand": {
        "id": "brd_Lw6ZZmNYhW0P9k0x",
        "title": "Zelf",
        "sub_brand_type": null,
        "is_primary": true
      },
      "statistics": {
        "post_count": 1280,
        "total_views": 5000000,
        "total_likes": 320000,
        "total_comments": 20000,
        "total_shares": 10000,
        "total_engagement": 350000,
        "total_earned_media_value_cents": 12500000,
        "engagement_rate": 0.07,
        "unique_creator_count": 412,
        "total_positive_nps": 245000,
        "total_neutral_nps": 84000,
        "total_negative_nps": 21000
      },
      "followers": {
        "total": 775000,
        "accounts": [
          {
            "platform": "instagram",
            "username": "zelfai",
            "followers": 420000
          },
          {
            "platform": "tiktok",
            "username": "zelfai",
            "followers": 260000
          },
          {
            "platform": "youtube",
            "username": "zelfai",
            "followers": 95000
          }
        ]
      }
    },
    {
      "brand": {
        "id": "brd_TOmS4tGtnsEhS9Fy",
        "title": "Northwind Apparel",
        "sub_brand_type": "COMPETITIVE",
        "is_primary": false
      },
      "statistics": {
        "post_count": 940,
        "total_views": 3500000,
        "total_likes": 180000,
        "total_comments": 11000,
        "total_shares": 5000,
        "total_engagement": 196000,
        "total_earned_media_value_cents": 7100000,
        "engagement_rate": 0.056,
        "unique_creator_count": 265,
        "total_positive_nps": 122500,
        "total_neutral_nps": 58800,
        "total_negative_nps": 14700
      },
      "followers": {
        "total": 458000,
        "accounts": [
          {
            "platform": "instagram",
            "username": "northwindapparel",
            "followers": 310000
          },
          {
            "platform": "tiktok",
            "username": "northwindapparel",
            "followers": 148000
          }
        ]
      }
    },
    {
      "brand": {
        "id": "brd_rMojoPskS9hZZVa0",
        "title": "Harborline",
        "sub_brand_type": "COMPETITIVE",
        "is_primary": false
      },
      "statistics": {
        "post_count": 510,
        "total_views": 2000000,
        "total_likes": 72000,
        "total_comments": 5400,
        "total_shares": 2600,
        "total_engagement": 80000,
        "total_earned_media_value_cents": 3400000,
        "engagement_rate": 0.04,
        "unique_creator_count": 148,
        "total_positive_nps": 46400,
        "total_neutral_nps": 26400,
        "total_negative_nps": 7200
      },
      "followers": {
        "total": 137000,
        "accounts": [
          {
            "platform": "instagram",
            "username": "harborline",
            "followers": 96000
          },
          {
            "platform": "youtube",
            "username": "harborline",
            "followers": 41000
          }
        ]
      }
    }
  ],
  "item_count": 3,
  "page": 1,
  "next": null,
  "previous": null
}

Get Brand Follower Time Series

GET/api/v1/analytics/follower_timeseries/analytics.follower_timeseries

Returns follower history for the top-level brand named by brand_id first, then each of its competitor sub-brands by title, bucketed by period. A brand appears only for the periods in which one of its owned handles was measured.

Follower counts carry forward: a handle with no reading in a period keeps the last one recorded before it.

Parameters

brand_idType: stringRequired

The top-level brand to analyse, as returned by brands.list. A sub-brand is refused with the id of the parent to use instead.

platformType: enum[]unique items true

Platforms to include, comma-separated. Defaults to all of them.

Show values
unique items
true
instagramtiktokyoutube
posted_afterType: string(date-time)

Start of the window (UTC, ISO 8601). Supplying more than one start is accepted and only one applies: this one wins over posted_within_hours, which wins over posted_within_days.

posted_beforeType: string(date-time)

End of the window (UTC, ISO 8601). Defaults to the current time, and a relative start is counted back from it.

posted_within_hoursType: integerminimum 1 · maximum 8760

Start of the window, counted back from posted_before or the current time, in hours (1-8760). posted_after wins over it; it wins over posted_within_days.

minimum
1
maximum
8760
posted_within_daysType: integerminimum 1 · maximum 365

Start of the window, counted back from posted_before or the current time, in days (1-365). Defaults to 7 when no date parameter is supplied, and loses to posted_after and posted_within_hours.

minimum
1
maximum
365
periodType: enum

Size of each bucket in the series. Defaults to day.

Show values
dayweekmonthyear

Returns FollowerTimeseries

brandType: AnalyticsBrand

The brand this row covers.

Show child attributes
brand.idType: stringread-only

Unique identifier for the brand.

brand.titleType: stringor null

Display name of the brand.

brand.is_primaryType: boolean

true for the brand the request named, false for a sub-brand.

brand.sub_brand_typeType: stringor nullread-only

COMPETITIVE or THEME for a sub-brand; null for the top-level brand the request named.

periodsType: FollowerPeriod[]

One entry per period, oldest first.

Show child attributes
periods[].followersType: integer

Followers across every owned handle.

periods[].start_dateType: string(date)

First day of the period.

periods[].end_dateType: string(date)

Last day of the period.

periods[].accountsType: FollowerAccount[]

Per handle counts that add up to followers.

Show child attributes
periods[].accounts[].platformType: string

The platform the handle is on.

periods[].accounts[].usernameType: string

The handle.

periods[].accounts[].followersType: integer

Follower count for this handle.

Responses

FollowerTimeseries

brandType: AnalyticsBrand

The brand this row covers.

Show child attributes
brand.idType: stringread-only

Unique identifier for the brand.

brand.titleType: stringor null

Display name of the brand.

brand.is_primaryType: boolean

true for the brand the request named, false for a sub-brand.

brand.sub_brand_typeType: stringor nullread-only

COMPETITIVE or THEME for a sub-brand; null for the top-level brand the request named.

periodsType: FollowerPeriod[]

One entry per period, oldest first.

Show child attributes
periods[].followersType: integer

Followers across every owned handle.

periods[].start_dateType: string(date)

First day of the period.

periods[].end_dateType: string(date)

Last day of the period.

periods[].accountsType: FollowerAccount[]

Per handle counts that add up to followers.

Show child attributes
periods[].accounts[].platformType: string

The platform the handle is on.

periods[].accounts[].usernameType: string

The handle.

periods[].accounts[].followersType: integer

Follower count for this handle.

Request

stringRequired
platformenum[]
string(date-time)
from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key="<your-api-key>")

result = client.analytics.follower_timeseries()
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "brand": {
        "id": "brd_Lw6ZZmNYhW0P9k0x",
        "title": "Zelf",
        "sub_brand_type": null,
        "is_primary": true
      },
      "periods": [
        {
          "start_date": "2026-09-28",
          "end_date": "2026-10-04",
          "followers": 742000,
          "accounts": [
            {
              "platform": "instagram",
              "username": "zelfai",
              "followers": 402000
            },
            {
              "platform": "tiktok",
              "username": "zelfai",
              "followers": 248000
            },
            {
              "platform": "youtube",
              "username": "zelfai",
              "followers": 92000
            }
          ]
        },
        {
          "start_date": "2026-10-05",
          "end_date": "2026-10-11",
          "followers": 758500,
          "accounts": [
            {
              "platform": "instagram",
              "username": "zelfai",
              "followers": 411000
            },
            {
              "platform": "tiktok",
              "username": "zelfai",
              "followers": 254000
            },
            {
              "platform": "youtube",
              "username": "zelfai",
              "followers": 93500
            }
          ]
        },
        {
          "start_date": "2026-10-12",
          "end_date": "2026-10-18",
          "followers": 775000,
          "accounts": [
            {
              "platform": "instagram",
              "username": "zelfai",
              "followers": 420000
            },
            {
              "platform": "tiktok",
              "username": "zelfai",
              "followers": 260000
            },
            {
              "platform": "youtube",
              "username": "zelfai",
              "followers": 95000
            }
          ]
        }
      ]
    },
    {
      "brand": {
        "id": "brd_TOmS4tGtnsEhS9Fy",
        "title": "Northwind Apparel",
        "sub_brand_type": "COMPETITIVE",
        "is_primary": false
      },
      "periods": [
        {
          "start_date": "2026-09-28",
          "end_date": "2026-10-04",
          "followers": 443000,
          "accounts": [
            {
              "platform": "instagram",
              "username": "northwindapparel",
              "followers": 301000
            },
            {
              "platform": "tiktok",
              "username": "northwindapparel",
              "followers": 142000
            }
          ]
        },
        {
          "start_date": "2026-10-05",
          "end_date": "2026-10-11",
          "followers": 450700,
          "accounts": [
            {
              "platform": "instagram",
              "username": "northwindapparel",
              "followers": 305500
            },
            {
              "platform": "tiktok",
              "username": "northwindapparel",
              "followers": 145200
            }
          ]
        },
        {
          "start_date": "2026-10-12",
          "end_date": "2026-10-18",
          "followers": 458000,
          "accounts": [
            {
              "platform": "instagram",
              "username": "northwindapparel",
              "followers": 310000
            },
            {
              "platform": "tiktok",
              "username": "northwindapparel",
              "followers": 148000
            }
          ]
        }
      ]
    }
  ],
  "item_count": 2,
  "page": 1,
  "next": null,
  "previous": null
}