zelf.developers

AI Analysis

Run AI analyses over content and comments. Start an analysis with a topic and a content filter, poll its runs for status, then fetch each run's result payload from ai_analysis.results.

Create AI Analysis

POST/api/v1/ai_analysis/ai_analysis.create

Starts an AI analysis over the content matched by content_filters (or its comments) for a given topic. Runs complete asynchronously; this method returns immediately with the created analysis and its initial runs.

The analysis runs over the highest-ranked matching content by content_filters.order_by, up to 500 posts or the limit configured for your workspace. When order_by is omitted, content is ranked by earned_media_value_cents descending.

The created analysis is returned as the single item in results. Take its id and poll ai_analysis.list until a run reports COMPLETED. An analysis can take an hour or more, so poll at a moderate interval; prefer the ai_analysis.completed webhook over frequent polling, which can trigger RATE_LIMIT_EXCEEDED. Once complete, retrieve the payload from ai_analysis.results, passing analysis_id=<id>.

Request body

nameType: stringRequiredmin length 1

A label for this analysis.

min length
1
topicType: stringRequiredmin length 1

The brand, product, person or event to analyze, as a short term. For example Levi's or Running shoes. Keep it under five words. Do not write a question: every run reports sentiment, price, quality, competitors and products for the topic. To narrow the posts, use content_filters.

min length
1
analysis_scopeType: enum[]default CONTENT

What to analyze: any of CONTENT, COMMENT. Defaults to ["CONTENT"].

Show values
default
CONTENT
CONTENTCOMMENT
content_filtersType: ContentFilterInputRequestRequired

Selects which content the analysis runs over. At least one of search, creator_id, creator_username, external_id, or brand_id is required to scope it. When both posted_after and posted_before are omitted, the analysis defaults to content from the last 7 days.

Show child attributes
content_filters.view_count_minType: integer

Include only content with at least this many views.

content_filters.view_count_maxType: integer

Include only content with at most this many views.

content_filters.comment_count_minType: integer

Include only content with at least this many comments.

content_filters.comment_count_maxType: integer

Include only content with at most this many comments.

content_filters.like_count_minType: integer

Include only content with at least this many likes.

content_filters.like_count_maxType: integer

Include only content with at most this many likes.

content_filters.share_count_minType: integer

Include only content with at least this many shares.

content_filters.share_count_maxType: integer

Include only content with at most this many shares.

content_filters.total_engagement_minType: integer

Minimum total engagement (likes + comments + shares).

content_filters.total_engagement_maxType: integer

Maximum total engagement (likes + comments + shares).

content_filters.earned_media_value_cents_minType: integer

Minimum estimated earned media value, in cents.

content_filters.earned_media_value_cents_maxType: integer

Maximum estimated earned media value, in cents.

content_filters.media_duration_minType: number(double)

Include only content at least this many seconds long.

content_filters.media_duration_maxType: number(double)

Include only content at most this many seconds long.

content_filters.posted_afterType: string(date-time)

Include only content posted at or after this UTC ISO-8601 time.

content_filters.posted_beforeType: string(date-time)

Include only content posted at or before this UTC ISO-8601 time.

content_filters.platformType: enum[]

Platforms to include. Any of: instagram, tiktok, youtube.

Show values
instagramtiktokyoutube
content_filters.languageType: string[]

Language codes to include, for example en or es.

content_filters.content_formType: enum

Content medium. One of: VIDEO, PHOTO.

Show values
VIDEOPHOTO
content_filters.searchType: stringmin length 1

Full-text search across caption, transcript, and summary. Space-separated terms are AND-ed.

min length
1
content_filters.creator_idType: stringmin length 1

Restrict to a single creator by id (from creators.list).

min length
1
content_filters.brand_idType: stringmin length 1

Restrict to an accessible brand id (from brands.list). Defaults to your own brand when omitted.

min length
1
content_filters.is_ownedType: boolean

Include only content owned by the brand.

content_filters.is_taggedType: boolean

Include only content where the brand is tagged.

content_filters.is_influencerType: boolean

Include only the brand's influencer content, or exclude it with false.

content_filters.external_idType: stringmin length 1

Platform-side post id. Matched exactly.

min length
1
content_filters.creator_usernameType: stringmin length 1

Creator username substring. Case-insensitive.

min length
1
content_filters.mention_typeType: enum[]

Restrict to these mention kinds. Any of: content, comment.

Show values
contentcomment
content_filters.mention_type_notType: enum[]

Exclude these mention kinds. Any of: content, comment.

Show values
contentcomment
content_filters.creator_follower_count_minType: integer

Include only content whose creator has at least this many followers.

content_filters.creator_follower_count_maxType: integer

Include only content whose creator has at most this many followers.

content_filters.engagement_rate_minType: number(double)

Minimum engagement as a fraction of views (e.g. 0.05 = 5%).

content_filters.engagement_rate_maxType: number(double)

Maximum engagement as a fraction of views (e.g. 0.05 = 5%).

content_filters.net_promoter_score_minType: integer

Minimum brand net promoter score for the content.

content_filters.net_promoter_score_maxType: integer

Maximum brand net promoter score for the content.

content_filters.posted_within_daysType: integerminimum 1 · maximum 365

Start of the window, counted back from the current time, in days (1-365). posted_after and posted_within_hours take precedence over it.

minimum
1
maximum
365
content_filters.posted_within_hoursType: integerminimum 1 · maximum 8760

Start of the window, counted back from the current time, in hours (1-8760). Takes precedence over posted_within_days. Counted back from posted_before when that is also supplied.

minimum
1
maximum
8760
content_filters.order_byType: string[]

Sort the selected content. Any of: posted_at, view_count, like_count, comment_count, share_count, engagement_rate, total_engagement, earned_media_value_cents, net_promoter_score, relevance_score. A bare key sorts descending; prefix with - to sort ascending. Determines which content is retained when the set is capped. Defaults to earned_media_value_cents descending.

Returns AiAnalysis

idType: stringread-only

ID of the analysis. Use this value on follow-up calls.

analysis_typeType: stringread-only

Always AI_ANALYSIS here.

nameType: string

The analysis label.

topicType: stringor null

The subject the analysis focuses on.

created_atType: string(date-time)

When the analysis was created (UTC, ISO-8601).

modified_atType: string(date-time)

When the analysis was last modified (UTC, ISO-8601).

analysesType: AiAnalysisRun[]

The runs that make up this analysis, one per scope, ordered newest first.

Show child attributes
analyses[].idType: stringread-only

ID of the analysis run.

analyses[].scopeType: string

What this run covers: CONTENT or COMMENT.

analyses[].statusType: stringread-only

Run status: one of IN_PROGRESS, COMPLETED, EMPTY_RESULT (finished with no matching content), or FAILED.

Responses

AiAnalysis

idType: stringread-only

ID of the analysis. Use this value on follow-up calls.

analysis_typeType: stringread-only

Always AI_ANALYSIS here.

nameType: string

The analysis label.

topicType: stringor null

The subject the analysis focuses on.

created_atType: string(date-time)

When the analysis was created (UTC, ISO-8601).

modified_atType: string(date-time)

When the analysis was last modified (UTC, ISO-8601).

analysesType: AiAnalysisRun[]

The runs that make up this analysis, one per scope, ordered newest first.

Show child attributes
analyses[].idType: stringread-only

ID of the analysis run.

analyses[].scopeType: string

What this run covers: CONTENT or COMMENT.

analyses[].statusType: stringread-only

Run status: one of IN_PROGRESS, COMPLETED, EMPTY_RESULT (finished with no matching content), or FAILED.

Request

stringRequired
stringRequired
analysis_scopeenum[]
from datetime import datetime, timezone

from zelf import ZelfAPIClient

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

result = client.ai_analysis.create(
    name="Zelf",
    topic="Zelf",
    analysis_scope=["CONTENT"],
    content_filters={
        "view_count_min": 42,
        "view_count_max": 42,
        "comment_count_min": 42,
        "comment_count_max": 42,
        "like_count_min": 42,
        "like_count_max": 42,
        "share_count_min": 42,
        "share_count_max": 42,
        "total_engagement_min": 42,
        "total_engagement_max": 42,
        "earned_media_value_cents_min": 42,
        "earned_media_value_cents_max": 42,
        "media_duration_min": 4.2,
        "media_duration_max": 4.2,
        "posted_after": datetime(2025, 1, 1, tzinfo=timezone.utc),
        "posted_before": datetime(2025, 1, 1, tzinfo=timezone.utc),
        "platform": ["instagram"],
        "language": ["en"],
        "content_form": "VIDEO",
        "search": "zelfai",
        "creator_id": "cr_pfqPv0FLsBRimHfi",
        "brand_id": "brd_Lw6ZZmNYhW0P9k0x",
        "is_owned": True,
        "is_tagged": True,
        "is_influencer": True,
        "external_id": "7376543210987654321",
        "creator_username": "zelfai",
        "mention_type": ["content"],
        "mention_type_not": ["comment"],
        "creator_follower_count_min": 42,
        "creator_follower_count_max": 42,
        "engagement_rate_min": 4.2,
        "engagement_rate_max": 4.2,
        "net_promoter_score_min": 42,
        "net_promoter_score_max": 42,
        "posted_within_days": 42,
        "posted_within_hours": 42,
        "order_by": ["view_count", "-posted_at"],
    },
)
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "id": "bod_huNssMQX4FTvALEY",
      "analysis_type": "AI_ANALYSIS",
      "name": "Zelf",
      "topic": "Zelf",
      "created_at": "2026-05-12T14:30:00Z",
      "modified_at": "2026-05-12T15:00:00Z",
      "analyses": [
        {
          "id": "ban_xJZFbcWNkF9M3brf",
          "scope": "CONTENT",
          "status": "COMPLETED"
        }
      ]
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}

List AI Analyses

GET/api/v1/ai_analysis/ai_analysis.list

Returns the AI analyses that have been created, ordered newest first, each with its runs and their current status. It lists the analyses available and tracks run progress without retrieving the full result payload.

An analysis id maps to analysis_id on ai_analysis.results and ai_analysis.contents, and each run's id maps to id on ai_analysis.results. The run result download is not included in this response; retrieve it from ai_analysis.results once a run reports COMPLETED (statuses: IN_PROGRESS, COMPLETED, EMPTY_RESULT, FAILED). Supply id to return a single analysis.

Parameters

idType: string

Optional analysis id. When supplied, only that analysis is returned. Returns INVALID_ID if malformed.

Returns AiAnalysis

idType: stringread-only

ID of the analysis. Use this value on follow-up calls.

analysis_typeType: stringread-only

Always AI_ANALYSIS here.

nameType: string

The analysis label.

topicType: stringor null

The subject the analysis focuses on.

created_atType: string(date-time)

When the analysis was created (UTC, ISO-8601).

modified_atType: string(date-time)

When the analysis was last modified (UTC, ISO-8601).

analysesType: AiAnalysisRun[]

The runs that make up this analysis, one per scope, ordered newest first.

Show child attributes
analyses[].idType: stringread-only

ID of the analysis run.

analyses[].scopeType: string

What this run covers: CONTENT or COMMENT.

analyses[].statusType: stringread-only

Run status: one of IN_PROGRESS, COMPLETED, EMPTY_RESULT (finished with no matching content), or FAILED.

Responses

AiAnalysis

idType: stringread-only

ID of the analysis. Use this value on follow-up calls.

analysis_typeType: stringread-only

Always AI_ANALYSIS here.

nameType: string

The analysis label.

topicType: stringor null

The subject the analysis focuses on.

created_atType: string(date-time)

When the analysis was created (UTC, ISO-8601).

modified_atType: string(date-time)

When the analysis was last modified (UTC, ISO-8601).

analysesType: AiAnalysisRun[]

The runs that make up this analysis, one per scope, ordered newest first.

Show child attributes
analyses[].idType: stringread-only

ID of the analysis run.

analyses[].scopeType: string

What this run covers: CONTENT or COMMENT.

analyses[].statusType: stringread-only

Run status: one of IN_PROGRESS, COMPLETED, EMPTY_RESULT (finished with no matching content), or FAILED.

Request

string
from zelf import ZelfAPIClient

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

result = client.ai_analysis.list()
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "id": "bod_huNssMQX4FTvALEY",
      "analysis_type": "AI_ANALYSIS",
      "name": "Zelf",
      "topic": "Zelf",
      "created_at": "2026-05-12T14:30:00Z",
      "modified_at": "2026-05-12T15:00:00Z",
      "analyses": [
        {
          "id": "ban_xJZFbcWNkF9M3brf",
          "scope": "CONTENT",
          "status": "COMPLETED"
        }
      ]
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}

Get AI Analysis Results

GET/api/v1/ai_analysis/results/ai_analysis.results

Returns each run's result, a signed, time-limited download of the analysis payload. Call this method after a run reaches COMPLETED; for earlier statuses the row is returned with a null result.

Supply analysis_id (the analysis id from ai_analysis.list) to return every run of that analysis, or id (a single run's id) to return one run. Exactly one is required. A malformed id returns INVALID_ID; omitting both returns VALIDATION_ERROR.

Parameters

analysis_idType: string

Analysis id (from ai_analysis.list). Returns every run of that analysis. Exactly one of analysis_id and id is required, and a request carrying both is rejected. Returns INVALID_ID if malformed.

idType: string

Single run id. Returns only that run. Exactly one of analysis_id and id is required, and a request carrying both is rejected. Returns INVALID_ID if malformed.

Returns AiAnalysisResult

idType: stringread-only

ID of the analysis run.

analysis_idType: stringread-only

ID of the analysis this run belongs to.

scopeType: string

What this run covers: CONTENT or COMMENT.

statusType: stringread-only

Run status: one of IN_PROGRESS, COMPLETED, EMPTY_RESULT (finished with no matching content), or FAILED.

resultType: ResultFileor nullread-only

Signed, time-limited download of the run's analysis payload: download_url (request it to retrieve the JSON), expires_at (Unix epoch seconds, approximately 24h TTL), and format (json). null until the run completes.

Show child attributes
result.expires_atType: integer

Unix epoch seconds after which download_url expires. Re-fetch the run to obtain a fresh URL.

result.formatType: string

Payload encoding. Always json.

result.download_urlType: string(uri)

Signed URL to request the JSON payload. Expires at expires_at.

created_atType: string(date-time)

When the run was created (UTC, ISO-8601).

modified_atType: string(date-time)

When the run was last modified (UTC, ISO-8601).

Responses

AiAnalysisResult

idType: stringread-only

ID of the analysis run.

analysis_idType: stringread-only

ID of the analysis this run belongs to.

scopeType: string

What this run covers: CONTENT or COMMENT.

statusType: stringread-only

Run status: one of IN_PROGRESS, COMPLETED, EMPTY_RESULT (finished with no matching content), or FAILED.

resultType: ResultFileor nullread-only

Signed, time-limited download of the run's analysis payload: download_url (request it to retrieve the JSON), expires_at (Unix epoch seconds, approximately 24h TTL), and format (json). null until the run completes.

Show child attributes
result.expires_atType: integer

Unix epoch seconds after which download_url expires. Re-fetch the run to obtain a fresh URL.

result.formatType: string

Payload encoding. Always json.

result.download_urlType: string(uri)

Signed URL to request the JSON payload. Expires at expires_at.

created_atType: string(date-time)

When the run was created (UTC, ISO-8601).

modified_atType: string(date-time)

When the run was last modified (UTC, ISO-8601).

Request

string
string
from zelf import ZelfAPIClient

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

result = client.ai_analysis.results()
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "id": "ban_xJZFbcWNkF9M3brf",
      "analysis_id": "bod_huNssMQX4FTvALEY",
      "scope": "CONTENT",
      "status": "COMPLETED",
      "result": {
        "download_url": "https://storage.googleapis.com/zelf-webhook-snapshots/ai_analysis/run_8f2c.json?X-Goog-Signature=...",
        "expires_at": 1718000000,
        "format": "json"
      },
      "created_at": "2026-05-12T14:30:00Z",
      "modified_at": "2026-05-12T15:00:00Z"
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}

List AI Analysis Content

GET/api/v1/ai_analysis/contents/ai_analysis.contents

Returns the content an AI analysis ran over, in the standard content shape. Use it to inspect the exact posts included in an analysis.

Requires analysis_id (an analysis id from ai_analysis.list). Brand-scoped fields (is_owned, is_tagged, net_promoter_score, ...) are null in this response.

Parameters

analysis_idType: stringRequired

Analysis id, as returned by ai_analysis.list.

Returns Content

idType: stringread-only

Unique identifier for this piece of content. Use it to retrieve the content anywhere a content id is accepted.

platform_post_idType: string

The post's identifier on its platform. This is the value at the end of the post's URL.

Examples:

  • Instagram: https://instagram.com/reel/abcd -> abcd
  • TikTok: https://www.tiktok.com/@username/video/12345678 -> 12345678
platformType: string

The platform the content was published on: instagram, tiktok or youtube.

content_formType: stringor null

Whether the content is a video or an image.

thumbnail_urlType: stringor null

URL of the content's thumbnail image.

posted_atType: string(date-time)or null

Time the content was originally published on its platform (UTC).

view_countType: integeror null

Total number of times the content has been viewed.

like_countType: integeror null

Total number of likes the content has received.

comment_countType: integeror null

Total number of comments on the content.

share_countType: integeror null

Total number of times the content has been shared.

total_engagementType: integeror null

Sum of the likes, comments, and shares the content has received.

languageType: stringor null

ISO 639 code of the content's primary language.

media_durationType: number(double)or null

Length of the media in seconds. Null when not known.

engagement_rateType: number(double)or nullread-only

Engagement per view (likes plus comments plus shares, divided by views). Null when the content has no recorded views.

earned_media_value_centsType: integeror nullread-only

Estimated marketing value of the content, in US cents.

creatorType: ContentCreatorread-only

The creator who published the content.

Show child attributes
creator.idType: stringread-only

Unique identifier for the creator.

creator.usernameType: stringor null

The creator's username or handle on the platform (without an @).

creator.nameType: stringor null

The creator's display name on the platform.

creator.platformType: stringor null

The platform the creator publishes on. One of instagram, tiktok, youtube.

creator.platform_handleType: stringor null

The platform-side identifier of the creator's account.

creator.platform_urlType: stringor null

Direct URL to the creator's profile on the platform.

creator.profile_picture_urlType: stringor null

URL of the creator's profile picture.

creator.profile_bioType: stringor null

The creator's profile bio as it appears on the platform.

creator.follower_countType: integeror null

The creator's follower count as of the most recent observation.

creator.active_content_countType: integeror null

Number of active content items attributed to the creator.

brand_idType: stringor nullread-only

Identifier of the brand that the brand-specific signals on this row (is_owned, is_tagged, is_influencer, mention_type, net_promoter_score) are scoped to. Returned as null when the request omits brand_id.

net_promoter_scoreType: integeror nullread-only

Net promoter score for the content from the perspective of the scoped brand. Returned as null when the request omits brand_id.

is_ownedType: booleanor nullread-only

Whether the scoped brand owns the content; that is, whether it was published by an account the brand controls. Returned as null when the request omits brand_id.

is_taggedType: booleanor nullread-only

Whether the post tags the scoped brand on the platform. Returned as null when the request omits brand_id.

is_influencerType: booleanor nullread-only

Whether the scoped brand counts the content as influencer content: it matches the brand's influencer terms, comes from an account on its influencer list, was reported as branded content by the platform, or was marked by hand. Content the brand owns is never influencer content. Returned as null when the request omits brand_id.

mention_typeType: stringor nullread-only

How the scoped brand is mentioned in the content. One of content or comment, or null when the brand is not mentioned. Returned as null when the request omits brand_id.

captionType: string

Short caption or title of the post (the primary user-visible text).

descriptionType: string

Long-form description of the post.

transcriptType: stringor null

Transcribed speech from the content's audio, when available.

platform_urlType: string

Direct URL to the post on its platform.

Examples:

  • https://instagram.com/reel/abcd
  • https://www.tiktok.com/@username/video/12345678
last_keywordType: stringor null

What the content was most recently collected under: a hashtag, a creator handle, a search term, or a brand identifier. Null when the content did not arrive through a collection task.

ai_summaryType: stringor null

Short AI-generated summary of the content.

hashtagsType: string[]

Hashtags used in the post, normalized to lowercase and without the leading #.

Responses

Content

idType: stringread-only

Unique identifier for this piece of content. Use it to retrieve the content anywhere a content id is accepted.

platform_post_idType: string

The post's identifier on its platform. This is the value at the end of the post's URL.

Examples:

  • Instagram: https://instagram.com/reel/abcd -> abcd
  • TikTok: https://www.tiktok.com/@username/video/12345678 -> 12345678
platformType: string

The platform the content was published on: instagram, tiktok or youtube.

content_formType: stringor null

Whether the content is a video or an image.

thumbnail_urlType: stringor null

URL of the content's thumbnail image.

posted_atType: string(date-time)or null

Time the content was originally published on its platform (UTC).

view_countType: integeror null

Total number of times the content has been viewed.

like_countType: integeror null

Total number of likes the content has received.

comment_countType: integeror null

Total number of comments on the content.

share_countType: integeror null

Total number of times the content has been shared.

total_engagementType: integeror null

Sum of the likes, comments, and shares the content has received.

languageType: stringor null

ISO 639 code of the content's primary language.

media_durationType: number(double)or null

Length of the media in seconds. Null when not known.

engagement_rateType: number(double)or nullread-only

Engagement per view (likes plus comments plus shares, divided by views). Null when the content has no recorded views.

earned_media_value_centsType: integeror nullread-only

Estimated marketing value of the content, in US cents.

creatorType: ContentCreatorread-only

The creator who published the content.

Show child attributes
creator.idType: stringread-only

Unique identifier for the creator.

creator.usernameType: stringor null

The creator's username or handle on the platform (without an @).

creator.nameType: stringor null

The creator's display name on the platform.

creator.platformType: stringor null

The platform the creator publishes on. One of instagram, tiktok, youtube.

creator.platform_handleType: stringor null

The platform-side identifier of the creator's account.

creator.platform_urlType: stringor null

Direct URL to the creator's profile on the platform.

creator.profile_picture_urlType: stringor null

URL of the creator's profile picture.

creator.profile_bioType: stringor null

The creator's profile bio as it appears on the platform.

creator.follower_countType: integeror null

The creator's follower count as of the most recent observation.

creator.active_content_countType: integeror null

Number of active content items attributed to the creator.

brand_idType: stringor nullread-only

Identifier of the brand that the brand-specific signals on this row (is_owned, is_tagged, is_influencer, mention_type, net_promoter_score) are scoped to. Returned as null when the request omits brand_id.

net_promoter_scoreType: integeror nullread-only

Net promoter score for the content from the perspective of the scoped brand. Returned as null when the request omits brand_id.

is_ownedType: booleanor nullread-only

Whether the scoped brand owns the content; that is, whether it was published by an account the brand controls. Returned as null when the request omits brand_id.

is_taggedType: booleanor nullread-only

Whether the post tags the scoped brand on the platform. Returned as null when the request omits brand_id.

is_influencerType: booleanor nullread-only

Whether the scoped brand counts the content as influencer content: it matches the brand's influencer terms, comes from an account on its influencer list, was reported as branded content by the platform, or was marked by hand. Content the brand owns is never influencer content. Returned as null when the request omits brand_id.

mention_typeType: stringor nullread-only

How the scoped brand is mentioned in the content. One of content or comment, or null when the brand is not mentioned. Returned as null when the request omits brand_id.

captionType: string

Short caption or title of the post (the primary user-visible text).

descriptionType: string

Long-form description of the post.

transcriptType: stringor null

Transcribed speech from the content's audio, when available.

platform_urlType: string

Direct URL to the post on its platform.

Examples:

  • https://instagram.com/reel/abcd
  • https://www.tiktok.com/@username/video/12345678
last_keywordType: stringor null

What the content was most recently collected under: a hashtag, a creator handle, a search term, or a brand identifier. Null when the content did not arrive through a collection task.

ai_summaryType: stringor null

Short AI-generated summary of the content.

hashtagsType: string[]

Hashtags used in the post, normalized to lowercase and without the leading #.

Request

stringRequired
from zelf import ZelfAPIClient

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

result = client.ai_analysis.contents()
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "id": "con_DZaWwnKo5HThZ9bu",
      "platform_post_id": "7376543210987654321",
      "platform": "instagram",
      "content_form": "VIDEO",
      "thumbnail_url": "https://cdn.hellozelf.com/thumbnails/zelfai-launch.png",
      "posted_at": "2026-05-12T16:00:00Z",
      "view_count": 184230,
      "like_count": 12840,
      "comment_count": 932,
      "share_count": 415,
      "total_engagement": 14187,
      "language": "en",
      "media_duration": 42,
      "engagement_rate": 0.077,
      "earned_media_value_cents": 248000,
      "creator": {
        "id": "cr_pfqPv0FLsBRimHfi",
        "username": "zelfai",
        "name": "Zelf",
        "platform": "instagram",
        "platform_handle": "zelfai",
        "platform_url": "https://www.instagram.com/zelfai",
        "profile_picture_url": "https://cdn.hellozelf.com/avatars/zelfai.png",
        "profile_bio": "Creator and content intelligence for modern brands.",
        "follower_count": 53120,
        "active_content_count": 217
      },
      "brand_id": "brd_Lw6ZZmNYhW0P9k0x",
      "net_promoter_score": 1,
      "is_owned": true,
      "is_tagged": true,
      "is_influencer": true,
      "mention_type": "content",
      "caption": "Behind the scenes at Zelf.",
      "description": "How Zelf turns social signals into creator insights.",
      "transcript": "We walk through how Zelf ranks creators by brand fit.",
      "platform_url": "https://www.instagram.com/zelfai",
      "last_keyword": "zelf creators",
      "ai_summary": "A product walkthrough of Zelf creator analytics.",
      "hashtags": [
        "zelfai",
        "creatoreconomy"
      ]
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}

Get AI Analysis Content Statistics

GET/api/v1/ai_analysis/contents/statistics/ai_analysis.content_statistics

Returns aggregate totals (post count, views, engagement, earned media value, and unique creators) over the content an AI analysis ran over.

Requires analysis_id (an analysis id from ai_analysis.list) and returns the same totals shape as content.statistics.

Parameters

analysis_idType: stringRequired

Analysis id, as returned by ai_analysis.list.

Returns ContentStatistics

post_countType: integer

Number of unique pieces of content in the filtered set.

total_viewsType: integer

Total views across the filtered set.

total_likesType: integer

Total likes across the filtered set.

total_commentsType: integer

Total comments across the filtered set.

total_sharesType: integer

Total shares across the filtered set.

total_engagementType: integer

Total engagement (likes + comments + shares) across the filtered set.

total_earned_media_value_centsType: integer

Total estimated marketing value across the filtered set, in US cents. Each piece of content contributes once even when multiple brand contexts match it through brand_id.

total_media_durationType: number(double)

Total media length in seconds across the filtered set.

engagement_rateType: number(double)or null

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

unique_creator_countType: integer

Number of distinct creators represented in the filtered set.

Responses

ContentStatistics

post_countType: integer

Number of unique pieces of content in the filtered set.

total_viewsType: integer

Total views across the filtered set.

total_likesType: integer

Total likes across the filtered set.

total_commentsType: integer

Total comments across the filtered set.

total_sharesType: integer

Total shares across the filtered set.

total_engagementType: integer

Total engagement (likes + comments + shares) across the filtered set.

total_earned_media_value_centsType: integer

Total estimated marketing value across the filtered set, in US cents. Each piece of content contributes once even when multiple brand contexts match it through brand_id.

total_media_durationType: number(double)

Total media length in seconds across the filtered set.

engagement_rateType: number(double)or null

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

unique_creator_countType: integer

Number of distinct creators represented in the filtered set.

Request

stringRequired
from zelf import ZelfAPIClient

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

result = client.ai_analysis.content_statistics()
print(result)
Response
{
  "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2026-01-01T00:00:00Z",
  "results": [
    {
      "post_count": 1280,
      "total_views": 4500000,
      "total_likes": 320000,
      "total_comments": 18000,
      "total_shares": 9500,
      "total_engagement": 347500,
      "total_earned_media_value_cents": 12500000,
      "total_media_duration": 53400,
      "engagement_rate": 0.077,
      "unique_creator_count": 412
    }
  ],
  "item_count": 1,
  "page": 1,
  "next": null,
  "previous": null
}