zelf.developers
Playbook

Monitor a brand

Owned, tagged and influencer posts, with the totals behind them.

10 min 4 steps

Scoping a request with brand_id changes what comes back. Posts are matched to the brand rather than to a keyword, and a set of fields that are null on an ordinary search start carrying values: whether the brand posted it, whether it was tagged, whether it came from an influencer.

Those fields are also filters, which is how you split a month of mentions into owned, earned and paid without running three different searches.

Every step shows the same call in all six Zelf clients and in cURL. Pick a language and the install line above the snippet switches with it. Each client reads your key from ZELF_API_KEY.

  1. 01Find your brand id
  2. 02List the mentions
  3. 03Split owned from earned
  4. 04Roll up the month

Find your brand id

GET/api/v1/brands/brands.list

Your key belongs to a brand, and that brand may have sub-brands under it. List them and pick the one you want to watch. A brand id is prefixed brd_.

idstringThe brand id, prefixed brd_.
titlestringDisplay name.
is_primarybooleanTrue for the brand your key belongs to, false for a sub-brand.
parent_brand_idstring or nullSet on a sub-brand, null on the primary.
pageintegerThis endpoint pages 50 at a time and does not accept page_size.
pip install zelf-sdk
import os

from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key=os.environ["ZELF_API_KEY"])

result = client.brands.list()
print(result)

List the mentions

GET/api/v1/content/content.list

brand_id satisfies the scope rule on its own, so you do not need a search term as well. Comma separate several ids to cover a brand and its sub-brands in one request; a post that matches more than one is still counted once.

brand_idstringComma separated. Turns on the brand fields below.
results[].mention_typecontent, commentWhere the brand was mentioned.
results[].net_promoter_scorenumberSentiment toward the brand on that post.
results[].earned_media_value_centsintegerValue attributed to the post, in cents.
pip install zelf-sdk
import os

from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key=os.environ["ZELF_API_KEY"])

result = client.content.list(
    brand_id="brd_1Ac5Pe9t",
    posted_within_days=30,
    order_by=["earned_media_value_cents"],
)
print(result)

Split owned from earned

GET/api/v1/content/statistics/content.statistics

The brand fields double as filters. is_owned is what the brand posted, is_tagged is what someone else posted and tagged it in, is_influencer is a creator in a paid relationship. Ask the statistics endpoint once per flag and you have the split.

is_ownedbooleanPosted by the brand itself.
is_taggedbooleanPosted by someone else, brand tagged.
is_influencerbooleanFrom a creator in a brand relationship.
mention_typecontent, commentComma separated. mention_type_not excludes instead.
net_promoter_score_minnumberAlso _max. Filters on sentiment toward the brand.
pip install zelf-sdk
import os

from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key=os.environ["ZELF_API_KEY"])

result = client.content.statistics(
    brand_id="brd_1Ac5Pe9t",
    posted_within_days=30,
    is_owned=True,
)
print(result)

These five filters, and sorting by net_promoter_score, only work on a brand scoped request. Without brand_id the call returns 400 BRAND_ID_REQUIRED, and error.details.blocked_by names the ones that caused it.

Roll up the month

GET/api/v1/content/statistics/content.statistics

One request, one row, totals over the whole match set rather than one page of it. This is the number that goes on a dashboard, and it is cheap enough to run per platform or per sub-brand.

post_countintegerMentions in the window.
unique_creator_countintegerDistinct creators behind them.
total_earned_media_value_centsintegerAttributed value for the window, in cents.
engagement_ratenumber or nullNull when total_views is zero.
total_views, total_likes, total_comments, total_shares, total_engagementintegerTotals over the set. total_media_duration comes back too.
pip install zelf-sdk
import os
from datetime import datetime, timezone

from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key=os.environ["ZELF_API_KEY"])

result = client.content.statistics(
    brand_id="brd_1Ac5Pe9t",
    posted_after=datetime(2026, 9, 1, tzinfo=timezone.utc),
    posted_before=datetime(2026, 9, 30, 23, 59, 59, tzinfo=timezone.utc),
)
print(result)

To ask a question about these posts rather than count them, hand the same filters to an AI analysis. content_filters takes brand_id too.