{ "components": { "schemas": { "CampaignMetricsDto": { "properties": { "affiliateLinksClicks": { "description": "Total number of clicks on affiliate links associated with the content.", "type": [ "number", "null" ] }, "affiliateLinksCommissionEarned": { "description": "Total commission earned from affiliate link sales associated with the content.", "type": [ "number", "null" ] }, "affiliateLinksConversionRate": { "description": "Conversion rate of affiliate links, calculated as conversions divided by clicks. Formula: affiliateLinksConversions / affiliateLinksClicks, aggregated across the campaign.", "type": [ "number", "null" ] }, "affiliateLinksConversions": { "description": "Total number of conversions attributed to affiliate links associated with the content.", "type": [ "number", "null" ] }, "affiliateLinksRoi": { "description": "Return on investment from affiliate link activity, calculated as commission earned relative to content cost. Formula: affiliateLinksCommissionEarned / estimatedContentCost, aggregated across the campaign.", "type": [ "number", "null" ] }, "affiliateLinksSales": { "description": "Total sales revenue generated through affiliate links associated with the content.", "type": [ "number", "null" ] }, "clicks": { "description": "Total number of clicks on the content.", "type": [ "number", "null" ] }, "comments": { "description": "Total number of comments on the content. For Twitch streams, this represents chat messages.", "type": [ "number", "null" ] }, "cpe": { "description": "Cost per engagement, calculated as the ratio of cost to total engagements. Exists in organic, paid, and blended (total) variants. A lower CPE indicates more cost-efficient content. Organic formula: estimatedContentCost / engagements. Paid variant (paidCpe): paidAdSpend / paidEngagements. Blended: (estimatedContentCost + paidAdSpend) / totalEngagements.", "type": [ "number", "null" ] }, "cpm": { "description": "Cost per thousand impressions, calculated as (cost / impressions) × 1,000. Exists in organic, paid, and blended (total) variants. A lower CPM indicates more cost-efficient content in terms of reach/visibility. Organic formula: (estimatedContentCost / impressions) × 1,000. Paid variant (paidCpm): (paidAdSpend / paidImpressions) × 1,000. Blended: ((estimatedContentCost + paidAdSpend) / totalImpressions) × 1,000.", "type": [ "number", "null" ] }, "crosspostedFacebookOnlyViews": { "description": "Number of views from Facebook only for a crossposted Instagram Reel. Only populated for reels that have been crossposted to Facebook. Represents the Facebook-specific portion of total crossposted views.", "type": [ "number", "null" ] }, "crosspostedViews": { "description": "Number of views from both Instagram and Facebook when an Instagram Reel is crossposted to Facebook. Only populated for reels that have been crossposted to Facebook.", "type": [ "number", "null" ] }, "engagementRate": { "description": "Percentage of impressions that resulted in an engagement action. Calculated as (engagements / impressions) × 100. Exists in organic, paid, and blended (total) variants. Aggregated across all posts in the campaign. Formula: (totalEngagements / totalImpressions) × 100. Paid variant (paidEngagementRate): (paidEngagements / paidImpressions) × 100.", "type": [ "number", "null" ] }, "engagements": { "description": "Total number of engagement actions on the content. Calculated as the sum of likes, comments, shares, clicks, and saves (where applicable). The paid engagement formula differs slightly by content type (e.g., TikTok excludes saves from paid engagements).", "type": [ "number", "null" ] }, "estimatedContentCost": { "description": "Estimated cost of the content based on the creator's payment allocation. Calculated by distributing the total campaign cost across content pieces. Sum of allocated content costs across all posts in the campaign. Formula per post: totalCreatorPayout / numberOfActivations.", "type": [ "number", "null" ] }, "estimatedRoi": { "description": "Return on investment calculated as the ratio of earned media value to estimated content cost. A value greater than 1.0 indicates the content generated more value than it cost. Formula: totalEarnedMediaValue / totalEstimatedContentCost across the campaign. Also exposed as estimatedRoi in this endpoint.", "type": [ "number", "null" ] }, "estimatedValueGenerated": { "description": "Estimated monetary value of organic engagement, calculated using industry benchmark rates. Calculated as the sum of value of likes, value of comments, value of impressions, and value of shares, using platform-specific benchmark multipliers. Also referred to as \"estimated value generated\" in some API responses. Aggregated across all posts in the campaign. Formula: valueOfLikes + valueOfComments + valueOfImpressions + valueOfShares, using platform-specific benchmark multipliers per content type.", "type": [ "number", "null" ] }, "impressions": { "description": "Total number of times the content was displayed. The source of this metric varies by content type: for video content types like reels, it may represent video plays; for story and streaming content, it may represent views.", "type": [ "number", "null" ] }, "impressionsPerPost": { "description": "Average number of impressions per content piece. Calculated as total impressions divided by the number of posts. Formula: totalImpressions / postsCount across all posts in the campaign.", "type": [ "number", "null" ] }, "influencersCount": { "description": "Total number of unique influencers/creators in the reporting scope. Exists in organic and paid variants. Total number of unique creators who have posts in this campaign.", "type": [ "number", "null" ] }, "likes": { "description": "Total number of likes received on the content.", "type": [ "number", "null" ] }, "organicReach": { "description": "Number of unique accounts that saw the content organically. Never add this to \"paidReach\" — reach counts unique viewers and the two audiences overlap; request the blended \"reach\" instead.", "type": [ "number", "null" ] }, "paidAdSpend": { "description": "Total amount spent on paid promotion of the content. Sourced from the advertising platform's reporting API.", "type": [ "number", "null" ] }, "paidClicks": { "description": "Paid variant. Total number of clicks on the content.", "type": [ "number", "null" ] }, "paidComments": { "description": "Paid variant. Total number of comments on the content. For Twitch streams, this represents chat messages.", "type": [ "number", "null" ] }, "paidCost": { "description": "Total incentive amount paid to the creator for the content. This represents creator compensation, not advertising spend. Total creator payout aggregated across the campaign.", "type": [ "number", "null" ] }, "paidCpe": { "description": "Paid variant. Cost per engagement, calculated as the ratio of cost to total engagements. Exists in organic, paid, and blended (total) variants. A lower CPE indicates more cost-efficient content. Organic formula: estimatedContentCost / engagements. Paid variant (paidCpe): paidAdSpend / paidEngagements. Blended: (estimatedContentCost + paidAdSpend) / totalEngagements.", "type": [ "number", "null" ] }, "paidCpm": { "description": "Paid variant. Cost per thousand impressions, calculated as (cost / impressions) × 1,000. Exists in organic, paid, and blended (total) variants. A lower CPM indicates more cost-efficient content in terms of reach/visibility. Organic formula: (estimatedContentCost / impressions) × 1,000. Paid variant (paidCpm): (paidAdSpend / paidImpressions) × 1,000. Blended: ((estimatedContentCost + paidAdSpend) / totalImpressions) × 1,000.", "type": [ "number", "null" ] }, "paidEngagementRate": { "description": "Paid variant. Percentage of impressions that resulted in an engagement action. Calculated as (engagements / impressions) × 100. Exists in organic, paid, and blended (total) variants. Aggregated across all posts in the campaign. Formula: (totalEngagements / totalImpressions) × 100. Paid variant (paidEngagementRate): (paidEngagements / paidImpressions) × 100.", "type": [ "number", "null" ] }, "paidEngagements": { "description": "Paid variant. Total number of engagement actions on the content. Calculated as the sum of likes, comments, shares, clicks, and saves (where applicable). The paid engagement formula differs slightly by content type (e.g., TikTok excludes saves from paid engagements).", "type": [ "number", "null" ] }, "paidImpressions": { "description": "Paid variant. Total number of times the content was displayed. The source of this metric varies by content type: for video content types like reels, it may represent video plays; for story and streaming content, it may represent views.", "type": [ "number", "null" ] }, "paidInfluencersCount": { "description": "Paid variant. Total number of unique influencers/creators in the reporting scope. Exists in organic and paid variants. Total number of unique creators who have posts in this campaign.", "type": [ "number", "null" ] }, "paidInitialPlays": { "description": "Number of initial video plays from paid promotion (auto-plays or first plays), as reported by Meta Ads.", "type": [ "number", "null" ] }, "paidLikes": { "description": "Paid variant. Total number of likes received on the content.", "type": [ "number", "null" ] }, "paidPostsCount": { "description": "Paid variant. Total number of content pieces (posts) in the reporting scope. Exists in organic and paid variants. Total number of posts published across the campaign.", "type": [ "number", "null" ] }, "paidReach": { "description": "Paid variant. Number of unique accounts that saw the content. Reach counts unique viewers, so the organic and paid figures cannot be added together — anyone who saw the content both ways would be counted twice. Request the blended total directly instead of summing \"organicReach\" and \"paidReach\".", "type": [ "number", "null" ] }, "paidReturnOnAdSpend": { "description": "Return on ad spend (ROAS) for the paid campaign, as reported by the advertising platform. Represents the revenue generated per unit of advertising spend.", "type": [ "number", "null" ] }, "paidSaves": { "description": "Paid variant. Number of times the content was saved/bookmarked.", "type": [ "number", "null" ] }, "paidShares": { "description": "Paid variant. Total number of shares of the content. For Pinterest, this represents pin saves. For Twitter/X, this represents retweets.", "type": [ "number", "null" ] }, "paidViews": { "description": "Paid variant. Number of times the content was viewed. For Instagram content, this is the new \"views\" metric from the Instagram Graph API (replacing deprecated \"impressions\"). For TikTok and YouTube, views represent organic video views.", "type": [ "number", "null" ] }, "postsCount": { "description": "Total number of content pieces (posts) in the reporting scope. Exists in organic and paid variants. Total number of posts published across the campaign.", "type": [ "number", "null" ] }, "potentialReach": { "deprecated": true, "description": "DEPRECATED — use \"organicReach\" instead; this field is still served unchanged and will be removed in a later release. Potential reach of the content, representing the total audience that could have seen the content.", "type": [ "number", "null" ] }, "reach": { "description": "Number of unique accounts that saw the content. Reach counts unique viewers, so the organic and paid figures cannot be added together — anyone who saw the content both ways would be counted twice. Request the blended total directly instead of summing \"organicReach\" and \"paidReach\".", "type": [ "number", "null" ] }, "replies": { "description": "Number of replies to the Instagram Story. This metric is specific to Instagram Stories and represents direct message replies to the story.", "type": [ "number", "null" ] }, "reposts": { "description": "Number of times the content was reposted by other users on Instagram. Note: availability may depend on the authentication method used for data collection.", "type": [ "number", "null" ] }, "saves": { "description": "Number of times the content was saved/bookmarked.", "type": [ "number", "null" ] }, "shares": { "description": "Total number of shares of the content. For Pinterest, this represents pin saves. For Twitter/X, this represents retweets.", "type": [ "number", "null" ] }, "totalInteractions": { "description": "Total number of interactions on the content as reported by Instagram. This is Instagram's own aggregate interaction count which may differ from our computed \"engagements\" metric.", "type": [ "number", "null" ] }, "trackingLinksClicks": { "description": "Total number of clicks on tracking links associated with the content.", "type": [ "number", "null" ] }, "trackingLinksConversionValue": { "description": "Total monetary value of conversions attributed to tracking links associated with the content.", "type": [ "number", "null" ] }, "trackingLinksConversions": { "description": "Total number of conversions attributed to tracking links associated with the content.", "type": [ "number", "null" ] }, "videoViewTotalTime": { "description": "Total cumulative watch time in milliseconds across all views of the video content. Useful for understanding audience retention and content engagement depth.", "type": [ "number", "null" ] }, "views": { "description": "Number of times the content was viewed. For Instagram content, this is the new \"views\" metric from the Instagram Graph API (replacing deprecated \"impressions\"). For TikTok and YouTube, views represent organic video views.", "type": [ "number", "null" ] } }, "type": "object" }, "CampaignPerformanceResponseDto": { "properties": { "campaignId": { "type": "number", "examples": [ 49761 ] }, "campaignName": { "type": [ "string", "null" ], "examples": [ "Summer Collection 2024" ] }, "description": { "type": [ "string", "null" ], "examples": [ "Campaign description" ] }, "firstPostDate": { "format": "date-time", "type": [ "string", "null" ], "examples": [ "2024-06-01T00:00:00Z" ] }, "instanceId": { "type": "string", "examples": [ "instance_123" ] }, "lastPostDate": { "format": "date-time", "type": [ "string", "null" ], "examples": [ "2024-08-15T00:00:00Z" ] }, "metrics": { "$ref": "#/components/schemas/CampaignMetricsDto" }, "uniqueContentTypes": { "items": { "type": "string" }, "type": [ "array", "null" ], "examples": [ [ "instagram_post", "tiktok" ] ] } }, "required": [ "campaignId", "campaignName", "instanceId", "description", "firstPostDate", "lastPostDate", "uniqueContentTypes", "metrics" ], "type": "object" }, "CampaignResponseDto": { "properties": { "campaignId": { "type": "number", "examples": [ 49761 ] }, "campaignName": { "type": [ "string", "null" ], "examples": [ "Summer Collection 2024" ] }, "description": { "type": [ "string", "null" ], "examples": [ "Seasonal product launch" ] }, "firstPostDate": { "format": "date-time", "type": [ "string", "null" ], "examples": [ "2024-06-15T00:00:00.000Z" ] }, "instanceId": { "type": "string", "examples": [ "instance_abc" ] }, "lastPostDate": { "format": "date-time", "type": [ "string", "null" ], "examples": [ "2024-08-15T00:00:00.000Z" ] }, "startDate": { "format": "date-time", "type": [ "string", "null" ], "examples": [ "2024-06-01T00:00:00.000Z" ] }, "status": { "type": [ "string", "null" ], "examples": [ "live" ] } }, "required": [ "campaignId", "campaignName", "instanceId", "description", "status", "startDate", "firstPostDate", "lastPostDate" ], "type": "object" }, "CreatorInfoDto": { "properties": { "creatorId": { "type": [ "number", "null" ], "examples": [ 12345 ] }, "fullName": { "type": [ "string", "null" ], "examples": [ "John Doe" ] }, "profilePictureUrl": { "type": [ "string", "null" ], "examples": [ "https://example.com/profile.jpg" ] }, "profiles": { "items": { "$ref": "#/components/schemas/CreatorProfileDto" }, "type": "array" } }, "required": [ "creatorId", "fullName", "profilePictureUrl", "profiles" ], "type": "object" }, "CreatorMetricsDto": { "properties": { "affiliateLinksClicks": { "description": "Total number of clicks on affiliate links associated with the content.", "type": [ "number", "null" ] }, "affiliateLinksCommissionEarned": { "description": "Total commission earned from affiliate link sales associated with the content.", "type": [ "number", "null" ] }, "affiliateLinksConversionRate": { "description": "Conversion rate of affiliate links, calculated as conversions divided by clicks. Formula: affiliateLinksConversions / affiliateLinksClicks for this creator.", "type": [ "number", "null" ] }, "affiliateLinksConversions": { "description": "Total number of conversions attributed to affiliate links associated with the content.", "type": [ "number", "null" ] }, "affiliateLinksRoi": { "description": "Return on investment from affiliate link activity, calculated as commission earned relative to content cost. Formula: affiliateLinksCommissionEarned / estimatedContentCost for this creator.", "type": [ "number", "null" ] }, "affiliateLinksSales": { "description": "Total sales revenue generated through affiliate links associated with the content.", "type": [ "number", "null" ] }, "avgWatchTime": { "description": "Average time in milliseconds that viewers spent watching the video. For Instagram Reels this is provided by the Instagram Graph API; for YouTube it comes from content engagements.", "type": [ "number", "null" ] }, "comments": { "description": "Total number of comments on the content. For Twitch streams, this represents chat messages.", "type": [ "number", "null" ] }, "cpe": { "description": "Cost per engagement, calculated as the ratio of cost to total engagements. Exists in organic, paid, and blended (total) variants. A lower CPE indicates more cost-efficient content. Organic formula: estimatedContentCost / engagements, where cost is the portion allocated to this creator. Paid variant (paidCpe): paidAdSpend / paidEngagements.", "type": [ "number", "null" ] }, "cpm": { "description": "Cost per thousand impressions, calculated as (cost / impressions) × 1,000. Exists in organic, paid, and blended (total) variants. A lower CPM indicates more cost-efficient content in terms of reach/visibility. Organic formula: (estimatedContentCost / impressions) × 1,000, where cost is the portion allocated to this creator. Paid variant (paidCpm): (paidAdSpend / paidImpressions) × 1,000.", "type": [ "number", "null" ] }, "crosspostedFacebookOnlyViews": { "description": "Number of views from Facebook only for a crossposted Instagram Reel. Only populated for reels that have been crossposted to Facebook. Represents the Facebook-specific portion of total crossposted views.", "type": [ "number", "null" ] }, "crosspostedViews": { "description": "Number of views from both Instagram and Facebook when an Instagram Reel is crossposted to Facebook. Only populated for reels that have been crossposted to Facebook.", "type": [ "number", "null" ] }, "engagementRate": { "description": "Percentage of impressions that resulted in an engagement action. Calculated as (engagements / impressions) × 100. Exists in organic, paid, and blended (total) variants. Aggregated across all posts by this creator in the selected scope. Formula: (totalEngagements / totalImpressions) × 100. Paid variant (paidEngagementRate): (paidEngagements / paidImpressions) × 100.", "type": [ "number", "null" ] }, "engagements": { "description": "Total number of engagement actions on the content. Calculated as the sum of likes, comments, shares, clicks, and saves (where applicable). The paid engagement formula differs slightly by content type (e.g., TikTok excludes saves from paid engagements).", "type": [ "number", "null" ] }, "estimatedContentCost": { "description": "Estimated cost of the content based on the creator's payment allocation. Calculated by distributing the total campaign cost across content pieces. Sum of allocated content costs for this creator's posts. Formula: totalCreatorPayout / numberOfActivations, summed across all their posts.", "type": [ "number", "null" ] }, "estimatedRoi": { "description": "Return on investment calculated as the ratio of earned media value to estimated content cost. A value greater than 1.0 indicates the content generated more value than it cost. Formula: totalEarnedMediaValue / totalEstimatedContentCost for this creator. Also exposed as estimatedRoi in this endpoint. Cost is the portion of campaign budget allocated to this creator.", "type": [ "number", "null" ] }, "estimatedValueGenerated": { "description": "Estimated monetary value of organic engagement, calculated using industry benchmark rates. Calculated as the sum of value of likes, value of comments, value of impressions, and value of shares, using platform-specific benchmark multipliers. Also referred to as \"estimated value generated\" in some API responses. Aggregated across all posts by this creator in the selected scope. Formula: valueOfLikes + valueOfComments + valueOfImpressions + valueOfShares, using platform-specific benchmark multipliers.", "type": [ "number", "null" ] }, "impressions": { "description": "Total number of times the content was displayed. The source of this metric varies by content type: for video content types like reels, it may represent video plays; for story and streaming content, it may represent views.", "type": [ "number", "null" ] }, "likes": { "description": "Total number of likes received on the content.", "type": [ "number", "null" ] }, "navigationSwipeForward": { "description": "Number of swipes to advance to the next Instagram Story. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "navigationTapBack": { "description": "Number of taps to go back to the previous Instagram Story. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "navigationTapExit": { "description": "Number of taps to exit the Instagram Story viewer. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "navigationTapForward": { "description": "Number of taps to skip to the next Instagram Story. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "organicReach": { "description": "Number of unique accounts that saw the content organically. Never add this to \"paidReach\" — reach counts unique viewers and the two audiences overlap; request the blended \"reach\" instead.", "type": [ "number", "null" ] }, "paidComments": { "description": "Paid variant. Total number of comments on the content. For Twitch streams, this represents chat messages.", "type": [ "number", "null" ] }, "paidCost": { "description": "Total incentive amount paid to the creator for the content. This represents creator compensation, not advertising spend. Total payout for this individual creator across their posts in the selected scope.", "type": [ "number", "null" ] }, "paidCpe": { "description": "Paid variant. Cost per engagement, calculated as the ratio of cost to total engagements. Exists in organic, paid, and blended (total) variants. A lower CPE indicates more cost-efficient content. Organic formula: estimatedContentCost / engagements, where cost is the portion allocated to this creator. Paid variant (paidCpe): paidAdSpend / paidEngagements.", "type": [ "number", "null" ] }, "paidCpm": { "description": "Paid variant. Cost per thousand impressions, calculated as (cost / impressions) × 1,000. Exists in organic, paid, and blended (total) variants. A lower CPM indicates more cost-efficient content in terms of reach/visibility. Organic formula: (estimatedContentCost / impressions) × 1,000, where cost is the portion allocated to this creator. Paid variant (paidCpm): (paidAdSpend / paidImpressions) × 1,000.", "type": [ "number", "null" ] }, "paidEngagementRate": { "description": "Paid variant. Percentage of impressions that resulted in an engagement action. Calculated as (engagements / impressions) × 100. Exists in organic, paid, and blended (total) variants. Aggregated across all posts by this creator in the selected scope. Formula: (totalEngagements / totalImpressions) × 100. Paid variant (paidEngagementRate): (paidEngagements / paidImpressions) × 100.", "type": [ "number", "null" ] }, "paidEngagements": { "description": "Paid variant. Total number of engagement actions on the content. Calculated as the sum of likes, comments, shares, clicks, and saves (where applicable). The paid engagement formula differs slightly by content type (e.g., TikTok excludes saves from paid engagements).", "type": [ "number", "null" ] }, "paidImpressions": { "description": "Paid variant. Total number of times the content was displayed. The source of this metric varies by content type: for video content types like reels, it may represent video plays; for story and streaming content, it may represent views.", "type": [ "number", "null" ] }, "paidLikes": { "description": "Paid variant. Total number of likes received on the content.", "type": [ "number", "null" ] }, "paidPostsCount": { "description": "Paid variant. Total number of content pieces (posts) in the reporting scope. Exists in organic and paid variants. Total number of posts published by this creator in the selected scope.", "type": [ "number", "null" ] }, "paidReach": { "description": "Paid variant. Number of unique accounts that saw the content. Reach counts unique viewers, so the organic and paid figures cannot be added together — anyone who saw the content both ways would be counted twice. Request the blended total directly instead of summing \"organicReach\" and \"paidReach\".", "type": [ "number", "null" ] }, "paidSaves": { "description": "Paid variant. Number of times the content was saved/bookmarked.", "type": [ "number", "null" ] }, "paidShares": { "description": "Paid variant. Total number of shares of the content. For Pinterest, this represents pin saves. For Twitter/X, this represents retweets.", "type": [ "number", "null" ] }, "paidViews": { "description": "Paid variant. Number of times the content was viewed. For Instagram content, this is the new \"views\" metric from the Instagram Graph API (replacing deprecated \"impressions\"). For TikTok and YouTube, views represent organic video views.", "type": [ "number", "null" ] }, "postsCount": { "description": "Total number of content pieces (posts) in the reporting scope. Exists in organic and paid variants. Total number of posts published by this creator in the selected scope.", "type": [ "number", "null" ] }, "potentialReach": { "deprecated": true, "description": "DEPRECATED — use \"organicReach\" instead; this field is still served unchanged and will be removed in a later release. Potential reach of the content, representing the total audience that could have seen the content.", "type": [ "number", "null" ] }, "reach": { "description": "Number of unique accounts that saw the content. Reach counts unique viewers, so the organic and paid figures cannot be added together — anyone who saw the content both ways would be counted twice. Request the blended total directly instead of summing \"organicReach\" and \"paidReach\".", "type": [ "number", "null" ] }, "replies": { "description": "Number of replies to the Instagram Story. This metric is specific to Instagram Stories and represents direct message replies to the story.", "type": [ "number", "null" ] }, "reposts": { "description": "Number of times the content was reposted by other users on Instagram. Note: availability may depend on the authentication method used for data collection.", "type": [ "number", "null" ] }, "saves": { "description": "Number of times the content was saved/bookmarked.", "type": [ "number", "null" ] }, "shares": { "description": "Total number of shares of the content. For Pinterest, this represents pin saves. For Twitter/X, this represents retweets.", "type": [ "number", "null" ] }, "totalInteractions": { "description": "Total number of interactions on the content as reported by Instagram. This is Instagram's own aggregate interaction count which may differ from our computed \"engagements\" metric.", "type": [ "number", "null" ] }, "trackingLinksClicks": { "description": "Total number of clicks on tracking links associated with the content.", "type": [ "number", "null" ] }, "trackingLinksConversionValue": { "description": "Total monetary value of conversions attributed to tracking links associated with the content.", "type": [ "number", "null" ] }, "trackingLinksConversions": { "description": "Total number of conversions attributed to tracking links associated with the content.", "type": [ "number", "null" ] }, "videoViewTotalTime": { "description": "Total cumulative watch time in milliseconds across all views of the video content. Useful for understanding audience retention and content engagement depth.", "type": [ "number", "null" ] }, "views": { "description": "Number of times the content was viewed. For Instagram content, this is the new \"views\" metric from the Instagram Graph API (replacing deprecated \"impressions\"). For TikTok and YouTube, views represent organic video views.", "type": [ "number", "null" ] } }, "type": "object" }, "CreatorPerformanceResponseDto": { "properties": { "creator": { "$ref": "#/components/schemas/CreatorInfoDto" }, "metrics": { "$ref": "#/components/schemas/CreatorMetricsDto" } }, "required": [ "creator", "metrics" ], "type": "object" }, "CreatorProfileDto": { "properties": { "contentType": { "type": "string", "examples": [ "instagram_post" ] }, "fullName": { "type": [ "string", "null" ], "examples": [ "John Doe" ] }, "handleName": { "type": "string", "examples": [ "johndoe" ] }, "profileImage": { "type": [ "string", "null" ], "examples": [ "https://example.com/profile.jpg" ] }, "profileLink": { "type": [ "string", "null" ], "examples": [ "https://instagram.com/johndoe" ] } }, "required": [ "handleName", "contentType", "fullName", "profileLink", "profileImage" ], "type": "object" }, "InstancesListResponseDto": { "properties": { "instanceIds": { "items": { "type": "string" }, "type": "array", "examples": [ [ "instance_123", "instance_456" ] ] } }, "required": [ "instanceIds" ], "type": "object" }, "NetworkMetricsDto": { "properties": { "avgWatchTime": { "description": "Average time in milliseconds that viewers spent watching the video. For Instagram Reels this is provided by the Instagram Graph API; for YouTube it comes from content engagements.", "type": [ "number", "null" ] }, "comments": { "description": "Total number of comments on the content. For Twitch streams, this represents chat messages.", "type": [ "number", "null" ] }, "cpe": { "description": "Cost per engagement, calculated as the ratio of cost to total engagements. Exists in organic, paid, and blended (total) variants. A lower CPE indicates more cost-efficient content. Organic formula: estimatedContentCost / engagements aggregated for this content type. Paid variant (paidCpe): paidAdSpend / paidEngagements.", "type": [ "number", "null" ] }, "cpm": { "description": "Cost per thousand impressions, calculated as (cost / impressions) × 1,000. Exists in organic, paid, and blended (total) variants. A lower CPM indicates more cost-efficient content in terms of reach/visibility. Organic formula: (estimatedContentCost / impressions) × 1,000 aggregated for this content type. Paid variant (paidCpm): (paidAdSpend / paidImpressions) × 1,000.", "type": [ "number", "null" ] }, "crosspostedFacebookOnlyViews": { "description": "Number of views from Facebook only for a crossposted Instagram Reel. Only populated for reels that have been crossposted to Facebook. Represents the Facebook-specific portion of total crossposted views.", "type": [ "number", "null" ] }, "crosspostedViews": { "description": "Number of views from both Instagram and Facebook when an Instagram Reel is crossposted to Facebook. Only populated for reels that have been crossposted to Facebook.", "type": [ "number", "null" ] }, "engagementRate": { "description": "Percentage of impressions that resulted in an engagement action. Calculated as (engagements / impressions) × 100. Exists in organic, paid, and blended (total) variants. Aggregated across all posts of this content type. Formula: (totalEngagements / totalImpressions) × 100. Paid variant (paidEngagementRate): (paidEngagements / paidImpressions) × 100.", "type": [ "number", "null" ] }, "engagements": { "description": "Total number of engagement actions on the content. Calculated as the sum of likes, comments, shares, clicks, and saves (where applicable). The paid engagement formula differs slightly by content type (e.g., TikTok excludes saves from paid engagements).", "type": [ "number", "null" ] }, "engagementsPerPost": { "description": "Average number of engagements per content piece. Calculated as total engagements divided by the number of posts. Formula: totalEngagements / postsCount for all posts of this content type.", "type": [ "number", "null" ] }, "estimatedValueGenerated": { "description": "Estimated monetary value of organic engagement, calculated using industry benchmark rates. Calculated as the sum of value of likes, value of comments, value of impressions, and value of shares, using platform-specific benchmark multipliers. Also referred to as \"estimated value generated\" in some API responses.", "type": [ "number", "null" ] }, "impressions": { "description": "Total number of times the content was displayed. The source of this metric varies by content type: for video content types like reels, it may represent video plays; for story and streaming content, it may represent views.", "type": [ "number", "null" ] }, "impressionsPerPost": { "description": "Average number of impressions per content piece. Calculated as total impressions divided by the number of posts. Formula: totalImpressions / postsCount for all posts of this content type.", "type": [ "number", "null" ] }, "likes": { "description": "Total number of likes received on the content.", "type": [ "number", "null" ] }, "navigationSwipeForward": { "description": "Number of swipes to advance to the next Instagram Story. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "navigationTapBack": { "description": "Number of taps to go back to the previous Instagram Story. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "navigationTapExit": { "description": "Number of taps to exit the Instagram Story viewer. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "navigationTapForward": { "description": "Number of taps to skip to the next Instagram Story. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "organicReach": { "description": "Number of unique accounts that saw the content organically. Never add this to \"paidReach\" — reach counts unique viewers and the two audiences overlap; request the blended \"reach\" instead.", "type": [ "number", "null" ] }, "paidAdSpend": { "description": "Total amount spent on paid promotion of the content. Sourced from the advertising platform's reporting API.", "type": [ "number", "null" ] }, "paidComments": { "description": "Paid variant. Total number of comments on the content. For Twitch streams, this represents chat messages.", "type": [ "number", "null" ] }, "paidCpe": { "description": "Paid variant. Cost per engagement, calculated as the ratio of cost to total engagements. Exists in organic, paid, and blended (total) variants. A lower CPE indicates more cost-efficient content. Organic formula: estimatedContentCost / engagements aggregated for this content type. Paid variant (paidCpe): paidAdSpend / paidEngagements.", "type": [ "number", "null" ] }, "paidCpm": { "description": "Paid variant. Cost per thousand impressions, calculated as (cost / impressions) × 1,000. Exists in organic, paid, and blended (total) variants. A lower CPM indicates more cost-efficient content in terms of reach/visibility. Organic formula: (estimatedContentCost / impressions) × 1,000 aggregated for this content type. Paid variant (paidCpm): (paidAdSpend / paidImpressions) × 1,000.", "type": [ "number", "null" ] }, "paidEngagementRate": { "description": "Paid variant. Percentage of impressions that resulted in an engagement action. Calculated as (engagements / impressions) × 100. Exists in organic, paid, and blended (total) variants. Aggregated across all posts of this content type. Formula: (totalEngagements / totalImpressions) × 100. Paid variant (paidEngagementRate): (paidEngagements / paidImpressions) × 100.", "type": [ "number", "null" ] }, "paidEngagements": { "description": "Paid variant. Total number of engagement actions on the content. Calculated as the sum of likes, comments, shares, clicks, and saves (where applicable). The paid engagement formula differs slightly by content type (e.g., TikTok excludes saves from paid engagements).", "type": [ "number", "null" ] }, "paidImpressions": { "description": "Paid variant. Total number of times the content was displayed. The source of this metric varies by content type: for video content types like reels, it may represent video plays; for story and streaming content, it may represent views.", "type": [ "number", "null" ] }, "paidLikes": { "description": "Paid variant. Total number of likes received on the content.", "type": [ "number", "null" ] }, "paidPostsCount": { "description": "Paid variant. Total number of content pieces (posts) in the reporting scope. Exists in organic and paid variants. Total number of posts of this content type in the selected scope.", "type": [ "number", "null" ] }, "paidReach": { "description": "Paid variant. Number of unique accounts that saw the content. Reach counts unique viewers, so the organic and paid figures cannot be added together — anyone who saw the content both ways would be counted twice. Request the blended total directly instead of summing \"organicReach\" and \"paidReach\".", "type": [ "number", "null" ] }, "paidReturnOnAdSpend": { "description": "Return on ad spend (ROAS) for the paid campaign, as reported by the advertising platform. Represents the revenue generated per unit of advertising spend.", "type": [ "number", "null" ] }, "paidSaves": { "description": "Paid variant. Number of times the content was saved/bookmarked.", "type": [ "number", "null" ] }, "paidShares": { "description": "Paid variant. Total number of shares of the content. For Pinterest, this represents pin saves. For Twitter/X, this represents retweets.", "type": [ "number", "null" ] }, "paidViews": { "description": "Paid variant. Number of times the content was viewed. For Instagram content, this is the new \"views\" metric from the Instagram Graph API (replacing deprecated \"impressions\"). For TikTok and YouTube, views represent organic video views.", "type": [ "number", "null" ] }, "postsCount": { "description": "Total number of content pieces (posts) in the reporting scope. Exists in organic and paid variants. Total number of posts of this content type in the selected scope.", "type": [ "number", "null" ] }, "potentialReach": { "deprecated": true, "description": "DEPRECATED — use \"organicReach\" instead; this field is still served unchanged and will be removed in a later release. Potential reach of the content, representing the total audience that could have seen the content.", "type": [ "number", "null" ] }, "reach": { "description": "Number of unique accounts that saw the content. Reach counts unique viewers, so the organic and paid figures cannot be added together — anyone who saw the content both ways would be counted twice. Request the blended total directly instead of summing \"organicReach\" and \"paidReach\".", "type": [ "number", "null" ] }, "replies": { "description": "Number of replies to the Instagram Story. This metric is specific to Instagram Stories and represents direct message replies to the story.", "type": [ "number", "null" ] }, "reposts": { "description": "Number of times the content was reposted by other users on Instagram. Note: availability may depend on the authentication method used for data collection.", "type": [ "number", "null" ] }, "saves": { "description": "Number of times the content was saved/bookmarked.", "type": [ "number", "null" ] }, "shares": { "description": "Total number of shares of the content. For Pinterest, this represents pin saves. For Twitter/X, this represents retweets.", "type": [ "number", "null" ] }, "totalInteractions": { "description": "Total number of interactions on the content as reported by Instagram. This is Instagram's own aggregate interaction count which may differ from our computed \"engagements\" metric.", "type": [ "number", "null" ] }, "videoViewTotalTime": { "description": "Total cumulative watch time in milliseconds across all views of the video content. Useful for understanding audience retention and content engagement depth.", "type": [ "number", "null" ] }, "views": { "description": "Number of times the content was viewed. For Instagram content, this is the new \"views\" metric from the Instagram Graph API (replacing deprecated \"impressions\"). For TikTok and YouTube, views represent organic video views.", "type": [ "number", "null" ] } }, "type": "object" }, "NetworkPerformanceResponseDto": { "properties": { "contentType": { "type": "string", "examples": [ "instagram_post" ] }, "metrics": { "$ref": "#/components/schemas/NetworkMetricsDto" } }, "required": [ "contentType", "metrics" ], "type": "object" }, "NetworkRoiResponseDto": { "properties": { "contentType": { "type": "string", "examples": [ "instagram_post" ] }, "estimatedContentCost": { "type": [ "number", "null" ], "examples": [ 2000 ] }, "returnOnInvestment": { "type": [ "number", "null" ], "examples": [ 2.5 ] }, "valueGenerated": { "type": [ "number", "null" ], "examples": [ 5000 ] }, "valueOfComments": { "type": [ "number", "null" ], "examples": [ 800 ] }, "valueOfImpressions": { "type": [ "number", "null" ], "examples": [ 1500 ] }, "valueOfLikes": { "type": [ "number", "null" ], "examples": [ 700 ] }, "valueOfShares": { "type": [ "number", "null" ], "examples": [ 1000 ] } }, "required": [ "contentType", "valueOfShares", "valueOfImpressions", "valueOfComments", "valueOfLikes", "valueGenerated", "estimatedContentCost", "returnOnInvestment" ], "type": "object" }, "OAuthTokenProblemDto": { "properties": { "detail": { "description": "Human-readable explanation for this occurrence of the problem. The exact wording may evolve — do not parse it programmatically; branch on `type` instead.", "type": "string", "examples": [ "The client ID or client secret is incorrect." ] }, "title": { "description": "Short, human-readable summary of the problem. Stable for a given failure mode, but not intended for programmatic branching — use `type` for that.", "enum": [ "Invalid Client Credentials", "Client Disabled", "No Accessible Instances", "Unsupported Media Type" ], "type": "string", "examples": [ "Invalid Client Credentials" ] }, "type": { "description": "Machine-readable error code. Integrations should branch on this value, not on `title` or HTTP status.\n\n- `ANL_00401` — the `clientId` is unknown or the `clientSecret` is incorrect (HTTP 401)\n- `ANL_00403` — the credentials are valid, but the client is disabled or has no accessible instances (HTTP 403)\n- `ANL_00415` — the request `Content-Type` is not `application/json` (HTTP 415)", "enum": [ "ANL_00401", "ANL_00403", "ANL_00415" ], "type": "string", "examples": [ "ANL_00401" ] } }, "required": [ "type", "title", "detail" ], "type": "object" }, "PerformanceMetricsDto": { "properties": { "affiliateLinksClicks": { "description": "Total number of clicks on affiliate links associated with the content.", "type": [ "number", "null" ] }, "affiliateLinksCommissionEarned": { "description": "Total commission earned from affiliate link sales associated with the content.", "type": [ "number", "null" ] }, "affiliateLinksConversionRate": { "description": "Conversion rate of affiliate links, calculated as conversions divided by clicks.", "type": [ "number", "null" ] }, "affiliateLinksConversions": { "description": "Total number of conversions attributed to affiliate links associated with the content.", "type": [ "number", "null" ] }, "affiliateLinksRoi": { "description": "Return on investment from affiliate link activity, calculated as commission earned relative to content cost.", "type": [ "number", "null" ] }, "affiliateLinksSales": { "description": "Total sales revenue generated through affiliate links associated with the content.", "type": [ "number", "null" ] }, "avgWatchTime": { "description": "Average time in milliseconds that viewers spent watching the video. For Instagram Reels this is provided by the Instagram Graph API; for YouTube it comes from content engagements.", "type": [ "number", "null" ] }, "clicks": { "description": "Total number of clicks on the content.", "type": [ "number", "null" ] }, "comments": { "description": "Total number of comments on the content. For Twitch streams, this represents chat messages.", "type": [ "number", "null" ] }, "cpe": { "description": "Cost per engagement, calculated as the ratio of cost to total engagements. Exists in organic, paid, and blended (total) variants. A lower CPE indicates more cost-efficient content.", "type": [ "number", "null" ] }, "cpm": { "description": "Cost per thousand impressions, calculated as (cost / impressions) × 1,000. Exists in organic, paid, and blended (total) variants. A lower CPM indicates more cost-efficient content in terms of reach/visibility.", "type": [ "number", "null" ] }, "crosspostedFacebookOnlyViews": { "description": "Number of views from Facebook only for a crossposted Instagram Reel. Only populated for reels that have been crossposted to Facebook. Represents the Facebook-specific portion of total crossposted views.", "type": [ "number", "null" ] }, "crosspostedViews": { "description": "Number of views from both Instagram and Facebook when an Instagram Reel is crossposted to Facebook. Only populated for reels that have been crossposted to Facebook.", "type": [ "number", "null" ] }, "engagementRate": { "description": "Percentage of impressions that resulted in an engagement action. Calculated as (engagements / impressions) × 100. Exists in organic, paid, and blended (total) variants.", "type": [ "number", "null" ] }, "engagements": { "description": "Total number of engagement actions on the content. Calculated as the sum of likes, comments, shares, clicks, and saves (where applicable). The paid engagement formula differs slightly by content type (e.g., TikTok excludes saves from paid engagements).", "type": [ "number", "null" ] }, "engagementsPerPost": { "description": "Average number of engagements per content piece. Calculated as total engagements divided by the number of posts.", "type": [ "number", "null" ] }, "estimatedContentCost": { "description": "Estimated cost of the content based on the creator's payment allocation. Calculated by distributing the total campaign cost across content pieces.", "type": [ "number", "null" ] }, "estimatedRoi": { "description": "Return on investment calculated as the ratio of earned media value to estimated content cost. A value greater than 1.0 indicates the content generated more value than it cost.", "type": [ "number", "null" ] }, "estimatedValueGenerated": { "description": "Estimated monetary value of organic engagement, calculated using industry benchmark rates. Calculated as the sum of value of likes, value of comments, value of impressions, and value of shares, using platform-specific benchmark multipliers. Also referred to as \"estimated value generated\" in some API responses.", "type": [ "number", "null" ] }, "followersAtPostDate": { "description": "Number of followers the creator had at the time the content was published. Useful for contextualizing engagement metrics relative to audience size.", "type": [ "number", "null" ] }, "impressions": { "description": "Total number of times the content was displayed. The source of this metric varies by content type: for video content types like reels, it may represent video plays; for story and streaming content, it may represent views.", "type": [ "number", "null" ] }, "impressionsPerPost": { "description": "Average number of impressions per content piece. Calculated as total impressions divided by the number of posts.", "type": [ "number", "null" ] }, "influencersCount": { "description": "Total number of unique influencers/creators in the reporting scope. Exists in organic and paid variants.", "type": [ "number", "null" ] }, "likes": { "description": "Total number of likes received on the content.", "type": [ "number", "null" ] }, "navigationSwipeForward": { "description": "Number of swipes to advance to the next Instagram Story. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "navigationTapBack": { "description": "Number of taps to go back to the previous Instagram Story. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "navigationTapExit": { "description": "Number of taps to exit the Instagram Story viewer. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "navigationTapForward": { "description": "Number of taps to skip to the next Instagram Story. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "organicReach": { "description": "Number of unique accounts that saw the content organically. Never add this to \"paidReach\" — reach counts unique viewers and the two audiences overlap; request the blended \"reach\" instead.", "type": [ "number", "null" ] }, "paidAdSpend": { "description": "Total amount spent on paid promotion of the content. Sourced from the advertising platform's reporting API.", "type": [ "number", "null" ] }, "paidClicks": { "description": "Paid variant. Total number of clicks on the content.", "type": [ "number", "null" ] }, "paidComments": { "description": "Paid variant. Total number of comments on the content. For Twitch streams, this represents chat messages.", "type": [ "number", "null" ] }, "paidCost": { "description": "Total incentive amount paid to the creator for the content. This represents creator compensation, not advertising spend.", "type": [ "number", "null" ] }, "paidCpe": { "description": "Paid variant. Cost per engagement, calculated as the ratio of cost to total engagements. Exists in organic, paid, and blended (total) variants. A lower CPE indicates more cost-efficient content.", "type": [ "number", "null" ] }, "paidCpm": { "description": "Paid variant. Cost per thousand impressions, calculated as (cost / impressions) × 1,000. Exists in organic, paid, and blended (total) variants. A lower CPM indicates more cost-efficient content in terms of reach/visibility.", "type": [ "number", "null" ] }, "paidEngagementRate": { "description": "Paid variant. Percentage of impressions that resulted in an engagement action. Calculated as (engagements / impressions) × 100. Exists in organic, paid, and blended (total) variants.", "type": [ "number", "null" ] }, "paidEngagements": { "description": "Paid variant. Total number of engagement actions on the content. Calculated as the sum of likes, comments, shares, clicks, and saves (where applicable). The paid engagement formula differs slightly by content type (e.g., TikTok excludes saves from paid engagements).", "type": [ "number", "null" ] }, "paidImpressions": { "description": "Paid variant. Total number of times the content was displayed. The source of this metric varies by content type: for video content types like reels, it may represent video plays; for story and streaming content, it may represent views.", "type": [ "number", "null" ] }, "paidInfluencersCount": { "description": "Paid variant. Total number of unique influencers/creators in the reporting scope. Exists in organic and paid variants.", "type": [ "number", "null" ] }, "paidInitialPlays": { "description": "Number of initial video plays from paid promotion (auto-plays or first plays), as reported by Meta Ads.", "type": [ "number", "null" ] }, "paidLikes": { "description": "Paid variant. Total number of likes received on the content.", "type": [ "number", "null" ] }, "paidPostsCount": { "description": "Paid variant. Total number of content pieces (posts) in the reporting scope. Exists in organic and paid variants.", "type": [ "number", "null" ] }, "paidReach": { "description": "Paid variant. Number of unique accounts that saw the content. Reach counts unique viewers, so the organic and paid figures cannot be added together — anyone who saw the content both ways would be counted twice. Request the blended total directly instead of summing \"organicReach\" and \"paidReach\".", "type": [ "number", "null" ] }, "paidReturnOnAdSpend": { "description": "Return on ad spend (ROAS) for the paid campaign, as reported by the advertising platform. Represents the revenue generated per unit of advertising spend.", "type": [ "number", "null" ] }, "paidSaves": { "description": "Paid variant. Number of times the content was saved/bookmarked.", "type": [ "number", "null" ] }, "paidShares": { "description": "Paid variant. Total number of shares of the content. For Pinterest, this represents pin saves. For Twitter/X, this represents retweets.", "type": [ "number", "null" ] }, "paidViews": { "description": "Paid variant. Number of times the content was viewed. For Instagram content, this is the new \"views\" metric from the Instagram Graph API (replacing deprecated \"impressions\"). For TikTok and YouTube, views represent organic video views.", "type": [ "number", "null" ] }, "postsCount": { "description": "Total number of content pieces (posts) in the reporting scope. Exists in organic and paid variants.", "type": [ "number", "null" ] }, "potentialReach": { "deprecated": true, "description": "DEPRECATED — use \"organicReach\" instead; this field is still served unchanged and will be removed in a later release. Potential reach of the content, representing the total audience that could have seen the content.", "type": [ "number", "null" ] }, "reach": { "description": "Number of unique accounts that saw the content. Reach counts unique viewers, so the organic and paid figures cannot be added together — anyone who saw the content both ways would be counted twice. Request the blended total directly instead of summing \"organicReach\" and \"paidReach\".", "type": [ "number", "null" ] }, "replies": { "description": "Number of replies to the Instagram Story. This metric is specific to Instagram Stories and represents direct message replies to the story.", "type": [ "number", "null" ] }, "reposts": { "description": "Number of times the content was reposted by other users on Instagram. Note: availability may depend on the authentication method used for data collection.", "type": [ "number", "null" ] }, "saves": { "description": "Number of times the content was saved/bookmarked.", "type": [ "number", "null" ] }, "shares": { "description": "Total number of shares of the content. For Pinterest, this represents pin saves. For Twitter/X, this represents retweets.", "type": [ "number", "null" ] }, "totalInteractions": { "description": "Total number of interactions on the content as reported by Instagram. This is Instagram's own aggregate interaction count which may differ from our computed \"engagements\" metric.", "type": [ "number", "null" ] }, "trackingLinksClicks": { "description": "Total number of clicks on tracking links associated with the content.", "type": [ "number", "null" ] }, "trackingLinksConversionValue": { "description": "Total monetary value of conversions attributed to tracking links associated with the content.", "type": [ "number", "null" ] }, "trackingLinksConversions": { "description": "Total number of conversions attributed to tracking links associated with the content.", "type": [ "number", "null" ] }, "videoViewTotalTime": { "description": "Total cumulative watch time in milliseconds across all views of the video content. Useful for understanding audience retention and content engagement depth.", "type": [ "number", "null" ] }, "views": { "description": "Number of times the content was viewed. For Instagram content, this is the new \"views\" metric from the Instagram Graph API (replacing deprecated \"impressions\"). For TikTok and YouTube, views represent organic video views.", "type": [ "number", "null" ] } }, "type": "object" }, "PerformanceSummaryMetricsDto": { "properties": { "affiliateLinksClicks": { "type": [ "number", "null" ], "examples": [ 3400 ] }, "affiliateLinksConversions": { "type": [ "number", "null" ], "examples": [ 210 ] }, "affiliateLinksSales": { "type": [ "number", "null" ], "examples": [ 18500 ] }, "campaignsCost": { "type": [ "number", "null" ], "examples": [ 15000 ] }, "cpe": { "type": [ "number", "null" ], "examples": [ 0.33 ] }, "cpm": { "type": [ "number", "null" ], "examples": [ 48.08 ] }, "engagementRate": { "type": [ "number", "null" ], "examples": [ 14.49 ] }, "engagements": { "type": [ "number", "null" ], "examples": [ 45200 ] }, "estimatedContentCost": { "type": [ "number", "null" ], "examples": [ 15000 ] }, "estimatedValueGenerated": { "type": [ "number", "null" ], "examples": [ 125000 ] }, "impressions": { "type": [ "number", "null" ], "examples": [ 312000 ] }, "organicReach": { "type": [ "number", "null" ], "examples": [ 240000 ] }, "paidAdSpend": { "type": [ "number", "null" ], "examples": [ 8500 ] }, "paidCpe": { "type": [ "number", "null" ], "examples": [ 0.66 ] }, "paidCpm": { "type": [ "number", "null" ], "examples": [ 45.95 ] }, "paidEngagementRate": { "type": [ "number", "null" ], "examples": [ 6.92 ] }, "paidEngagements": { "type": [ "number", "null" ], "examples": [ 12800 ] }, "paidImpressions": { "type": [ "number", "null" ], "examples": [ 185000 ] }, "paidPostsCount": { "type": [ "number", "null" ], "examples": [ 18 ] }, "paidReach": { "type": [ "number", "null" ], "examples": [ 40000 ] }, "paidReturnOnAdSpend": { "type": [ "number", "null" ], "examples": [ 3.8 ] }, "paidViews": { "type": [ "number", "null" ], "examples": [ 42000 ] }, "postsCount": { "type": [ "number", "null" ], "examples": [ 142 ] }, "reach": { "type": [ "number", "null" ], "examples": [ 280000 ] }, "returnOnInvestment": { "type": [ "number", "null" ], "examples": [ 8.33 ] }, "trackingLinksClicks": { "type": [ "number", "null" ], "examples": [ 1200 ] }, "trackingLinksConversionValue": { "type": [ "number", "null" ], "examples": [ 42000 ] }, "trackingLinksConversions": { "type": [ "number", "null" ], "examples": [ 85 ] }, "views": { "type": [ "number", "null" ], "examples": [ 95000 ] } }, "required": [ "engagements", "impressions", "engagementRate", "postsCount", "reach", "organicReach", "views", "estimatedValueGenerated", "estimatedContentCost", "campaignsCost", "returnOnInvestment", "cpe", "cpm", "paidEngagements", "paidImpressions", "paidEngagementRate", "paidPostsCount", "paidReach", "paidViews", "paidAdSpend", "paidReturnOnAdSpend", "paidCpe", "paidCpm", "trackingLinksClicks", "trackingLinksConversions", "trackingLinksConversionValue", "affiliateLinksClicks", "affiliateLinksConversions", "affiliateLinksSales" ], "type": "object" }, "PerformanceSummaryResponseDto": { "properties": { "metrics": { "$ref": "#/components/schemas/PerformanceSummaryMetricsDto" } }, "required": [ "metrics" ], "type": "object" }, "PostMetricsDto": { "properties": { "avgWatchTime": { "description": "Average time in milliseconds that viewers spent watching the video. For Instagram Reels this is provided by the Instagram Graph API; for YouTube it comes from content engagements.", "type": [ "number", "null" ] }, "comments": { "description": "Total number of comments on the content. For Twitch streams, this represents chat messages.", "type": [ "number", "null" ] }, "cpe": { "description": "Cost per engagement, calculated as the ratio of cost to total engagements. Exists in organic, paid, and blended (total) variants. A lower CPE indicates more cost-efficient content. Organic formula: allocatedContentCost / engagements for this individual post. Paid variant (paidCpe): paidAdSpend / paidEngagements.", "type": [ "number", "null" ] }, "cpm": { "description": "Cost per thousand impressions, calculated as (cost / impressions) × 1,000. Exists in organic, paid, and blended (total) variants. A lower CPM indicates more cost-efficient content in terms of reach/visibility. Organic formula: (allocatedContentCost / impressions) × 1,000 for this individual post. Paid variant (paidCpm): (paidAdSpend / paidImpressions) × 1,000.", "type": [ "number", "null" ] }, "crosspostedFacebookOnlyViews": { "description": "Number of views from Facebook only for a crossposted Instagram Reel. Only populated for reels that have been crossposted to Facebook. Represents the Facebook-specific portion of total crossposted views.", "type": [ "number", "null" ] }, "crosspostedViews": { "description": "Number of views from both Instagram and Facebook when an Instagram Reel is crossposted to Facebook. Only populated for reels that have been crossposted to Facebook.", "type": [ "number", "null" ] }, "engagementRate": { "description": "Percentage of impressions that resulted in an engagement action. Calculated as (engagements / impressions) × 100. Exists in organic, paid, and blended (total) variants. Per-post value. Formula: (engagements / impressions) × 100. Paid variant (paidEngagementRate): (paidEngagements / paidImpressions) × 100.", "type": [ "number", "null" ] }, "engagements": { "description": "Total number of engagement actions on the content. Calculated as the sum of likes, comments, shares, clicks, and saves (where applicable). The paid engagement formula differs slightly by content type (e.g., TikTok excludes saves from paid engagements).", "type": [ "number", "null" ] }, "estimatedValueGenerated": { "description": "Estimated monetary value of organic engagement, calculated using industry benchmark rates. Calculated as the sum of value of likes, value of comments, value of impressions, and value of shares, using platform-specific benchmark multipliers. Also referred to as \"estimated value generated\" in some API responses. Per-post value. Formula: valueOfLikes + valueOfComments + valueOfImpressions + valueOfShares using the benchmark multipliers for this post's content type. Note: instagram_reel uses impressions × VPV; instagram_story uses only the impressions component.", "type": [ "number", "null" ] }, "followersAtPostDate": { "description": "Number of followers the creator had at the time the content was published. Useful for contextualizing engagement metrics relative to audience size.", "type": [ "number", "null" ] }, "impressions": { "description": "Total number of times the content was displayed. The source of this metric varies by content type: for video content types like reels, it may represent video plays; for story and streaming content, it may represent views.", "type": [ "number", "null" ] }, "likes": { "description": "Total number of likes received on the content.", "type": [ "number", "null" ] }, "navigationSwipeForward": { "description": "Number of swipes to advance to the next Instagram Story. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "navigationTapBack": { "description": "Number of taps to go back to the previous Instagram Story. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "navigationTapExit": { "description": "Number of taps to exit the Instagram Story viewer. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "navigationTapForward": { "description": "Number of taps to skip to the next Instagram Story. A sub-metric of the total navigation count.", "type": [ "number", "null" ] }, "organicReach": { "description": "Number of unique accounts that saw the content organically. Never add this to \"paidReach\" — reach counts unique viewers and the two audiences overlap; request the blended \"reach\" instead.", "type": [ "number", "null" ] }, "paidComments": { "description": "Paid variant. Total number of comments on the content. For Twitch streams, this represents chat messages.", "type": [ "number", "null" ] }, "paidCpe": { "description": "Paid variant. Cost per engagement, calculated as the ratio of cost to total engagements. Exists in organic, paid, and blended (total) variants. A lower CPE indicates more cost-efficient content. Organic formula: allocatedContentCost / engagements for this individual post. Paid variant (paidCpe): paidAdSpend / paidEngagements.", "type": [ "number", "null" ] }, "paidCpm": { "description": "Paid variant. Cost per thousand impressions, calculated as (cost / impressions) × 1,000. Exists in organic, paid, and blended (total) variants. A lower CPM indicates more cost-efficient content in terms of reach/visibility. Organic formula: (allocatedContentCost / impressions) × 1,000 for this individual post. Paid variant (paidCpm): (paidAdSpend / paidImpressions) × 1,000.", "type": [ "number", "null" ] }, "paidEngagementRate": { "description": "Paid variant. Percentage of impressions that resulted in an engagement action. Calculated as (engagements / impressions) × 100. Exists in organic, paid, and blended (total) variants. Per-post value. Formula: (engagements / impressions) × 100. Paid variant (paidEngagementRate): (paidEngagements / paidImpressions) × 100.", "type": [ "number", "null" ] }, "paidEngagements": { "description": "Paid variant. Total number of engagement actions on the content. Calculated as the sum of likes, comments, shares, clicks, and saves (where applicable). The paid engagement formula differs slightly by content type (e.g., TikTok excludes saves from paid engagements).", "type": [ "number", "null" ] }, "paidImpressions": { "description": "Paid variant. Total number of times the content was displayed. The source of this metric varies by content type: for video content types like reels, it may represent video plays; for story and streaming content, it may represent views.", "type": [ "number", "null" ] }, "paidLikes": { "description": "Paid variant. Total number of likes received on the content.", "type": [ "number", "null" ] }, "paidReach": { "description": "Paid variant. Number of unique accounts that saw the content. Reach counts unique viewers, so the organic and paid figures cannot be added together — anyone who saw the content both ways would be counted twice. Request the blended total directly instead of summing \"organicReach\" and \"paidReach\".", "type": [ "number", "null" ] }, "paidSaves": { "description": "Paid variant. Number of times the content was saved/bookmarked.", "type": [ "number", "null" ] }, "paidShares": { "description": "Paid variant. Total number of shares of the content. For Pinterest, this represents pin saves. For Twitter/X, this represents retweets.", "type": [ "number", "null" ] }, "paidViews": { "description": "Paid variant. Number of times the content was viewed. For Instagram content, this is the new \"views\" metric from the Instagram Graph API (replacing deprecated \"impressions\"). For TikTok and YouTube, views represent organic video views.", "type": [ "number", "null" ] }, "potentialReach": { "deprecated": true, "description": "DEPRECATED — use \"organicReach\" instead; this field is still served unchanged and will be removed in a later release. Potential reach of the content, representing the total audience that could have seen the content.", "type": [ "number", "null" ] }, "reach": { "description": "Number of unique accounts that saw the content. Reach counts unique viewers, so the organic and paid figures cannot be added together — anyone who saw the content both ways would be counted twice. Request the blended total directly instead of summing \"organicReach\" and \"paidReach\".", "type": [ "number", "null" ] }, "replies": { "description": "Number of replies to the Instagram Story. This metric is specific to Instagram Stories and represents direct message replies to the story.", "type": [ "number", "null" ] }, "reposts": { "description": "Number of times the content was reposted by other users on Instagram. Note: availability may depend on the authentication method used for data collection.", "type": [ "number", "null" ] }, "saves": { "description": "Number of times the content was saved/bookmarked.", "type": [ "number", "null" ] }, "shares": { "description": "Total number of shares of the content. For Pinterest, this represents pin saves. For Twitter/X, this represents retweets.", "type": [ "number", "null" ] }, "totalInteractions": { "description": "Total number of interactions on the content as reported by Instagram. This is Instagram's own aggregate interaction count which may differ from our computed \"engagements\" metric.", "type": [ "number", "null" ] }, "videoViewTotalTime": { "description": "Total cumulative watch time in milliseconds across all views of the video content. Useful for understanding audience retention and content engagement depth.", "type": [ "number", "null" ] }, "views": { "description": "Number of times the content was viewed. For Instagram content, this is the new \"views\" metric from the Instagram Graph API (replacing deprecated \"impressions\"). For TikTok and YouTube, views represent organic video views.", "type": [ "number", "null" ] } }, "type": "object" }, "PostPerformanceResponseDto": { "properties": { "campaignId": { "type": "number", "examples": [ 49761 ] }, "contentImageUrl": { "type": "string", "examples": [ "https://example.com/image.jpg" ] }, "contentType": { "type": [ "string", "null" ], "examples": [ "instagram_post" ] }, "contentUrl": { "type": "string", "examples": [ "https://www.instagram.com/p/ABC123/" ] }, "creatorId": { "type": "number", "examples": [ 12345 ] }, "creatorProfile": { "allOf": [ { "$ref": "#/components/schemas/CreatorProfileDto" } ], "type": [ "object", "null" ] }, "instanceId": { "type": "string", "examples": [ "instance_123" ] }, "metrics": { "$ref": "#/components/schemas/PostMetricsDto" }, "postDate": { "format": "date-time", "type": "string", "examples": [ "2024-05-01T12:00:00Z" ] }, "postId": { "type": "number", "examples": [ 1234 ] } }, "required": [ "postId", "creatorId", "instanceId", "campaignId", "postDate", "contentType", "contentUrl", "contentImageUrl", "creatorProfile", "metrics" ], "type": "object" }, "ProblemDetailDto": { "properties": { "detail": { "description": "A human-readable explanation specific to this occurrence of the problem. May include the offending parameter value and the list of accepted values to help the caller recover.", "type": "string", "examples": [ "Invalid sortProperty 'invalidField' for /creators. Valid values are: engagements, impressions, ..." ] }, "title": { "description": "A short, human-readable summary of the problem type. Stable for a given `type` (e.g. `Invalid Sort Property` for `ANL_00422`, `Token Expired` for `ANL_00498`) but not intended for programmatic branching — use `type` for that.", "type": "string", "examples": [ "Invalid Sort Property" ] }, "type": { "description": "A machine-readable error code identifying the problem type.\n\n- `ANL_00401` — the `clientId` is unknown, the `clientSecret` is incorrect, or the JWT is missing, malformed, or failed verification (HTTP 401)\n- `ANL_00403` — the credentials or JWT are valid, but access is not permitted: the client is disabled, has no accessible instances, or the requested `instanceIds` are not bound to it (HTTP 403)\n- `ANL_00498` — the JWT has expired; request a new token via `/oauth/token` (HTTP 401)\n\n- `ANL_00400` — one or more query parameters failed validation (HTTP 400)\n- `ANL_00422` — the `sortProperty` value is not supported for this endpoint, or is not available for the selected `platform` / `contentType` filter (HTTP 400)\n- `ANL_00404` — the requested resource could not be found (HTTP 404)\n- `ANL_00415` — the request `Content-Type` is not supported; use `application/json` (HTTP 415)\n\n- `ANL_00500` — an unexpected server-side error occurred; the request was not processed and the credentials are not implicated, so retry with exponential backoff (HTTP 500)", "enum": [ "ANL_00400", "ANL_00401", "ANL_00498", "ANL_00403", "ANL_00422", "ANL_00500", "ANL_00404", "ANL_00415" ], "type": "string", "examples": [ "ANL_00400" ] } }, "required": [ "type", "title", "detail" ], "type": "object" }, "TimeseriesDataPointDto": { "properties": { "endDate": { "description": "End of the time bucket (inclusive)", "type": "string", "examples": [ "2024-10-31" ] }, "metrics": { "$ref": "#/components/schemas/TimeseriesMetricsDto" }, "startDate": { "description": "Start of the time bucket (inclusive)", "type": "string", "examples": [ "2024-10-01" ] } }, "required": [ "startDate", "endDate", "metrics" ], "type": "object" }, "TimeseriesMetricsDto": { "properties": { "clicks": { "description": "Total number of clicks on the content.", "type": [ "number", "null" ] }, "comments": { "description": "Total number of comments on the content. For Twitch streams, this represents chat messages.", "type": [ "number", "null" ] }, "cpe": { "description": "Cost per engagement, calculated as the ratio of cost to total engagements. Exists in organic, paid, and blended (total) variants. A lower CPE indicates more cost-efficient content.", "type": [ "number", "null" ] }, "cpm": { "description": "Cost per thousand impressions, calculated as (cost / impressions) × 1,000. Exists in organic, paid, and blended (total) variants. A lower CPM indicates more cost-efficient content in terms of reach/visibility.", "type": [ "number", "null" ] }, "engagementRate": { "description": "Percentage of impressions that resulted in an engagement action. Calculated as (engagements / impressions) × 100. Exists in organic, paid, and blended (total) variants.", "type": [ "number", "null" ] }, "engagements": { "description": "Total number of engagement actions on the content. Calculated as the sum of likes, comments, shares, clicks, and saves (where applicable). The paid engagement formula differs slightly by content type (e.g., TikTok excludes saves from paid engagements).", "type": [ "number", "null" ] }, "estimatedValueGenerated": { "description": "Estimated monetary value of organic engagement, calculated using industry benchmark rates. Calculated as the sum of value of likes, value of comments, value of impressions, and value of shares, using platform-specific benchmark multipliers. Also referred to as \"estimated value generated\" in some API responses.", "type": [ "number", "null" ] }, "impressions": { "description": "Total number of times the content was displayed. The source of this metric varies by content type: for video content types like reels, it may represent video plays; for story and streaming content, it may represent views.", "type": [ "number", "null" ] }, "likes": { "description": "Total number of likes received on the content.", "type": [ "number", "null" ] }, "organicReach": { "description": "Number of unique accounts that saw the content organically. Never add this to \"paidReach\" — reach counts unique viewers and the two audiences overlap; request the blended \"reach\" instead.", "type": [ "number", "null" ] }, "paidComments": { "description": "Paid variant. Total number of comments on the content. For Twitch streams, this represents chat messages.", "type": [ "number", "null" ] }, "paidEngagementRate": { "description": "Paid variant. Percentage of impressions that resulted in an engagement action. Calculated as (engagements / impressions) × 100. Exists in organic, paid, and blended (total) variants.", "type": [ "number", "null" ] }, "paidEngagements": { "description": "Paid variant. Total number of engagement actions on the content. Calculated as the sum of likes, comments, shares, clicks, and saves (where applicable). The paid engagement formula differs slightly by content type (e.g., TikTok excludes saves from paid engagements).", "type": [ "number", "null" ] }, "paidImpressions": { "description": "Paid variant. Total number of times the content was displayed. The source of this metric varies by content type: for video content types like reels, it may represent video plays; for story and streaming content, it may represent views.", "type": [ "number", "null" ] }, "paidLikes": { "description": "Paid variant. Total number of likes received on the content.", "type": [ "number", "null" ] }, "paidReach": { "description": "Paid variant. Number of unique accounts that saw the content. Reach counts unique viewers, so the organic and paid figures cannot be added together — anyone who saw the content both ways would be counted twice. Request the blended total directly instead of summing \"organicReach\" and \"paidReach\".", "type": [ "number", "null" ] }, "paidShares": { "description": "Paid variant. Total number of shares of the content. For Pinterest, this represents pin saves. For Twitter/X, this represents retweets.", "type": [ "number", "null" ] }, "paidViews": { "description": "Paid variant. Number of times the content was viewed. For Instagram content, this is the new \"views\" metric from the Instagram Graph API (replacing deprecated \"impressions\"). For TikTok and YouTube, views represent organic video views.", "type": [ "number", "null" ] }, "postsCount": { "description": "Total number of content pieces (posts) in the reporting scope. Exists in organic and paid variants.", "type": [ "number", "null" ] }, "reach": { "description": "Number of unique accounts that saw the content. Reach counts unique viewers, so the organic and paid figures cannot be added together — anyone who saw the content both ways would be counted twice. Request the blended total directly instead of summing \"organicReach\" and \"paidReach\".", "type": [ "number", "null" ] }, "shares": { "description": "Total number of shares of the content. For Pinterest, this represents pin saves. For Twitter/X, this represents retweets.", "type": [ "number", "null" ] }, "views": { "description": "Number of times the content was viewed. For Instagram content, this is the new \"views\" metric from the Instagram Graph API (replacing deprecated \"impressions\"). For TikTok and YouTube, views represent organic video views.", "type": [ "number", "null" ] } }, "type": "object" }, "TokenRequestDto": { "properties": { "clientId": { "description": "Client ID required to get the JWT token used for authentication", "type": "string", "examples": [ "client_id_123" ] }, "clientSecret": { "description": "Client Secret required to get the JWT token used for authentication", "type": "string", "examples": [ "client_secret_456" ] } }, "required": [ "clientId", "clientSecret" ], "type": "object" }, "TokenResponseDto": { "properties": { "jwt": { "description": "JWT used as `Authorization: Bearer ` on Reporting API routes.", "type": "string", "examples": [ "" ] } }, "required": [ "jwt" ], "type": "object" } }, "securitySchemes": { "JWT": { "bearerFormat": "JWT", "description": "JWT obtained from the OAuth2 token endpoint", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "email": "urvash.chheda@later.com", "name": "Developer", "url": "https://help-influence.later.com/hc/en-us" }, "description": "", "termsOfService": "https://later.com/terms/", "title": "Later Influence™ Reporting API", "version": "2.0.0" }, "openapi": "3.1.1", "paths": { "/oauth/token": { "post": { "description": "Exchange client credentials for a JWT. Returns `jwt` on success. Failed requests return `application/problem+json` (RFC 9457) with `type`, `title`, and `detail` (no `status` in body):\n\n- **401** (`type: ANL_00401`) — the `clientId` or `clientSecret` was not accepted. Check the credentials before retrying.\n- **403** (`type: ANL_00403`) — the credentials were accepted, but the client is not permitted to issue a token. Retrying will not help; contact your Later account team.\n- **415** (`type: ANL_00415`) — the request `Content-Type` is not `application/json`.", "operationId": "getToken", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequestDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponseDto" } } }, "description": "Success. Returns `jwt` for use as `Authorization: Bearer ` on all reporting routes." }, "400": { "description": "Malformed JSON body or missing required fields" }, "401": { "content": { "application/problem+json": { "examples": { "invalidCredentials": { "summary": "ANL_00401 — Unknown clientId or incorrect clientSecret", "value": { "detail": "The client ID or client secret is incorrect.", "title": "Invalid Client Credentials", "type": "ANL_00401" } } }, "schema": { "$ref": "#/components/schemas/OAuthTokenProblemDto" } } }, "description": "Authentication failed — the `clientId` or `clientSecret` was not accepted (`ANL_00401`)." }, "403": { "content": { "application/problem+json": { "examples": { "clientDisabled": { "summary": "ANL_00403 — Client disabled", "value": { "detail": "This API client has been disabled.", "title": "Client Disabled", "type": "ANL_00403" } }, "noAccessibleInstances": { "summary": "ANL_00403 — No accessible instances", "value": { "detail": "This client has no active instance associations.", "title": "No Accessible Instances", "type": "ANL_00403" } } }, "schema": { "$ref": "#/components/schemas/OAuthTokenProblemDto" } } }, "description": "Authorization failed — the credentials were accepted, but the client is not permitted to issue a token (`ANL_00403`). Retrying will not help; contact your Later account team." }, "415": { "content": { "application/problem+json": { "examples": { "unsupportedMediaType": { "summary": "ANL_00415 — Unsupported Content-Type", "value": { "detail": "The request Content-Type is not supported. Use application/json.", "title": "Unsupported Media Type", "type": "ANL_00415" } } }, "schema": { "$ref": "#/components/schemas/OAuthTokenProblemDto" } } }, "description": "Unsupported media type — the request `Content-Type` is not `application/json` (`ANL_00415`)." }, "500": { "description": "Unexpected error while issuing token" } }, "security": [], "summary": "Generate OAuth Token", "tags": [ "Authentication" ] } }, "/v2/campaigns": { "get": { "description": "Returns a flat list of all campaigns across the given instances with basic metadata.\n\n**What is included per campaign:**\n- Campaign ID, name, description, and status\n- Start date, first post date, and last post date\n- Instance ID the campaign belongs to\n\nNo performance metrics are included — use `GET /campaigns/performance` for metrics.", "operationId": "getCampaignsList", "parameters": [ { "description": "Maximum number of items to return per page. Choose any value on the first request, then keep it unchanged on every subsequent request that passes a `nextCursor` from this endpoint. To change the page size, start a new walk by omitting `nextCursor`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "number", "examples": [ 50 ] } }, { "description": "Opaque cursor returned by the previous page. Omit on the first request. Cursors are tied to the query parameters of the request that produced them; to paginate, keep every parameter identical across requests and only vary `nextCursor`. To change filters, sort, or `limit`, start a new walk by omitting `nextCursor`.", "in": "query", "name": "nextCursor", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CampaignResponseDto" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" }, "examples": { "default": { "value": { "data": [ { "campaignId": 49761, "campaignName": "Summer Collection 2024", "description": "Seasonal product launch", "firstPostDate": "2024-06-15T00:00:00.000Z", "instanceId": "instance_abc", "lastPostDate": "2024-08-15T00:00:00.000Z", "startDate": "2024-06-01T00:00:00.000Z", "status": "live" }, { "campaignId": 49802, "campaignName": "Fall Influencer Push", "description": null, "firstPostDate": null, "instanceId": "instance_abc", "lastPostDate": null, "startDate": "2024-09-01T00:00:00.000Z", "status": "draft" } ], "nextCursor": "eyJ2ZXJzaW9uIjoxfQ" } } } } }, "description": "List of campaigns with metadata" }, "400": { "content": { "application/problem+json": { "examples": { "ANL_00400": { "summary": "ANL_00400 — Query parameter validation failed", "value": { "detail": "startDate must be a Date instance; endDate must be a Date instance", "title": "Validation Error", "type": "ANL_00400" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "One or more query parameters failed validation (`ANL_00400`)" }, "401": { "content": { "application/problem+json": { "examples": { "expired": { "summary": "ANL_00401 — Token expired", "value": { "detail": "The JWT has expired; request a new token via /oauth/token.", "title": "Unauthorized", "type": "ANL_00401" } }, "invalid": { "summary": "ANL_00401 — Missing, malformed or invalid JWT", "value": { "detail": "The authentication token could not be validated. Please ensure your token is valid and try again.", "title": "Unauthorized", "type": "ANL_00401" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authentication failed — the JWT is missing, malformed, invalid, or expired (`ANL_00401`). Request a new token via `POST /oauth/token` before retrying." }, "403": { "content": { "application/problem+json": { "examples": { "forbidden": { "summary": "ANL_00403 — Instance scope not accessible with this token", "value": { "detail": "Access denied. The requested instance IDs are not accessible with this token.", "title": "Forbidden", "type": "ANL_00403" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authorization failed — the JWT is valid but the requested scope is not accessible with this token (`ANL_00403`). Typically one or more `instanceIds` are not bound to the client." }, "500": { "content": { "application/problem+json": { "examples": { "ANL_00500": { "summary": "ANL_00500 — Unexpected server error", "value": { "detail": "An unexpected error occurred while processing the request.", "title": "Internal Error", "type": "ANL_00500" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "An unexpected error occurred while processing the request (`ANL_00500`). The request was not processed and the credentials are not implicated — retry with exponential backoff." } }, "security": [ { "JWT": [] } ], "summary": "List campaigns", "tags": [ "Campaign Level" ] } }, "/v2/campaigns/performance": { "get": { "description": "Returns a list of campaigns with their performance metrics.\n\n**What is included per campaign:**\n- Campaign metadata (title, description, date range, platforms used)\n- Metrics requested via the `metrics` query parameter", "operationId": "getCampaigns", "parameters": [ { "description": "Start of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "startDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-01-01" ] } }, { "description": "End of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "endDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-12-31" ] } }, { "description": "Specify one or more metric names to include in the response. Only the selected metrics will be returned within the `metrics` object for each result item.\n\n**Supported values:**\n`likes`, `comments`, `shares`, `clicks`, `saves`, `impressions`, `reach`, `organicReach`, `engagements`, `views`, `totalInteractions`, `replies`, `reposts`, `potentialReach`, `videoViewTotalTime`, `crosspostedViews`, `crosspostedFacebookOnlyViews`, `engagementRate`, `postsCount`, `influencersCount`, `impressionsPerPost`, `estimatedValueGenerated`, `estimatedContentCost`, `estimatedRoi`, `cpe`, `cpm`, `paidLikes`, `paidComments`, `paidShares`, `paidClicks`, `paidImpressions`, `paidEngagements`, `paidEngagementRate`, `paidViews`, `paidReach`, `paidSaves`, `paidCpe`, `paidCpm`, `paidPostsCount`, `paidInfluencersCount`, `paidAdSpend`, `paidReturnOnAdSpend`, `paidInitialPlays`, `paidCost`, `trackingLinksClicks`, `trackingLinksConversions`, `trackingLinksConversionValue`, `affiliateLinksClicks`, `affiliateLinksConversions`, `affiliateLinksConversionRate`, `affiliateLinksSales`, `affiliateLinksCommissionEarned`, `affiliateLinksRoi`\n\nMetric availability depends on the applied `platform` or `contentType` filters. Some metrics are restricted to specific content types (for example, `crosspostedFacebookOnlyViews` is only available for Instagram Reels). Requesting unsupported metrics will result in a `400` error, along with a list of valid metrics for the current filters.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "metrics", "required": true, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific instances. When omitted, the request is evaluated against every instance associated with your OAuth client; supply one or more values to narrow the response to a subset. Values must be drawn from the set bound to your client credentials — requesting an instance outside that set returns `403` with `type: ANL_00403`.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "instanceIds", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific campaigns. When omitted, all campaigns are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "campaignIds", "required": false, "schema": { "items": { "type": "number" }, "maxItems": 50, "type": "array" } }, { "description": "Filter by top-level platform. Selecting a platform includes all its content types (e.g. `instagram` includes `instagram_post`, `instagram_reel`, `instagram_story`).\n\nCannot be combined with `contentType` — provide only one of the two.\n\nWhen omitted (and `contentType` is also omitted), all platforms are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "platform", "required": false, "schema": { "items": { "enum": [ "instagram", "tiktok", "facebook", "youtube", "twitter", "linkedin", "pinterest", "snapchat", "blog", "twitch" ], "type": "string" }, "type": "array" } }, { "description": "Filter by specific content type for granular filtering beyond top-level platforms.\n\n- `instagram_post`, `instagram_reel`, `instagram_story` — specific Instagram content formats\n- `facebook_post`, `facebook_live`, `facebook_group`, `facebook_reel` — specific Facebook content formats\n- `tiktok`, `youtube_video`, `youtube_shorts` — platform-specific types\n\nCannot be combined with `platform` — provide only one of the two.\n\nWhen omitted (and `platform` is also omitted), all content types are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "contentType", "required": false, "schema": { "items": { "enum": [ "instagram_post", "instagram_reel", "instagram_story", "facebook_post", "facebook_live", "facebook_group", "facebook_reel", "tiktok", "youtube_video", "youtube_shorts", "twitter", "linkedin", "pinterest", "snapchat_story", "blog", "twitch_stream" ], "type": "string" }, "type": "array" } }, { "description": "Controls which date dimension is used for filtering.\n\n- **`post_date`** (default): filters by the date the content was originally published. Best for analyzing content output and creator activity over time.\n- **`performance_date`**: returns metrics recorded within the requested date range, regardless of when the content was originally published. Best for understanding how campaigns performed during a specific reporting window.\n\nExample: a post published on Jan 5 that receives engagement on Feb 10 will appear in a Feb 1–28 query with `performance_date`, but in a Jan 1–31 query with `post_date`.", "in": "query", "name": "dateBasis", "required": false, "schema": { "default": "post_date", "enum": [ "post_date", "performance_date" ], "type": "string", "examples": [ "post_date" ] } }, { "description": "Maximum number of items to return per page. Choose any value on the first request, then keep it unchanged on every subsequent request that passes a `nextCursor` from this endpoint. To change the page size, start a new walk by omitting `nextCursor`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "number", "examples": [ 50 ] } }, { "description": "Opaque cursor returned by the previous page. Omit on the first request. Cursors are tied to the query parameters of the request that produced them; to paginate, keep every parameter identical across requests and only vary `nextCursor`. To change filters, sort, or `limit`, start a new walk by omitting `nextCursor`.", "in": "query", "name": "nextCursor", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Metric or field name to sort results by. Use `sortDirection` (`ASC` or `DESC`, default: `DESC`) to control the order.\n\n**Supported values:** `likes`, `comments`, `shares`, `clicks`, `saves`, `impressions`, `reach`, `organicReach`, `engagements`, `views`, `totalInteractions`, `replies`, `reposts`, `potentialReach`, `videoViewTotalTime`, `crosspostedViews`, `crosspostedFacebookOnlyViews`, `engagementRate`, `postsCount`, `influencersCount`, `impressionsPerPost`, `estimatedValueGenerated`, `estimatedContentCost`, `estimatedRoi`, `cpe`, `cpm`, `paidLikes`, `paidComments`, `paidShares`, `paidClicks`, `paidImpressions`, `paidEngagements`, `paidEngagementRate`, `paidViews`, `paidReach`, `paidSaves`, `paidCpe`, `paidCpm`, `paidPostsCount`, `paidInfluencersCount`, `paidAdSpend`, `paidReturnOnAdSpend`, `paidInitialPlays`, `paidCost`, `trackingLinksClicks`, `trackingLinksConversions`, `trackingLinksConversionValue`, `affiliateLinksClicks`, `affiliateLinksConversions`, `affiliateLinksConversionRate`, `affiliateLinksSales`, `affiliateLinksCommissionEarned`, `affiliateLinksRoi`, `firstPostDate`, `lastPostDate`\n\n> **Note:** When `platform` or `contentType` filters are applied, only metrics supported by the selected content types are accepted as sort properties. The API returns an error with the valid list when an unsupported sort property is used with a filter.", "in": "query", "name": "sortProperty", "required": false, "schema": { "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "sortDirection", "required": false, "schema": { "default": "DESC", "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CampaignPerformanceResponseDto" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" }, "examples": { "default": { "value": { "data": [ { "campaignId": 49761, "campaignName": "Summer Collection 2024", "description": "Seasonal product launch", "firstPostDate": "2024-06-01T00:00:00.000Z", "instanceId": "instance_abc", "lastPostDate": "2024-08-15T00:00:00.000Z", "metrics": { "affiliateLinksClicks": 1200, "affiliateLinksCommissionEarned": 540, "affiliateLinksConversionRate": 5.67, "affiliateLinksConversions": 68, "affiliateLinksRoi": 9, "affiliateLinksSales": 5400, "clicks": 1500, "cpe": 1.56, "cpm": 110.62, "engagementRate": 7.08, "engagements": 3200, "estimatedContentCost": 5000, "estimatedRoi": 5.6, "estimatedValueGenerated": 28000, "impressions": 45200, "impressionsPerPost": 1076.19, "influencersCount": 12, "paidAdSpend": 3400, "paidClicks": 420, "paidCpe": 3.12, "paidCpm": 265.63, "paidEngagementRate": 8.59, "paidEngagements": 1100, "paidImpressions": 12800, "paidInfluencersCount": 4, "paidPostsCount": 8, "paidReturnOnAdSpend": 2.8, "postsCount": 42, "reach": 38000, "trackingLinksClicks": 850, "trackingLinksConversionValue": 12600, "trackingLinksConversions": 42 }, "uniqueContentTypes": [ "instagram_post", "tiktok" ] } ], "nextCursor": "eyJ2ZXJzaW9uIjoxfQ" } } } } }, "description": "Campaign performance metrics" }, "400": { "content": { "application/problem+json": { "examples": { "ANL_00400": { "summary": "ANL_00400 — Query parameter validation failed", "value": { "detail": "startDate must be a Date instance; endDate must be a Date instance", "title": "Validation Error", "type": "ANL_00400" } }, "ANL_00422": { "summary": "ANL_00422 — Invalid sort property", "value": { "detail": "Invalid sortProperty 'invalidField' for /creators. Valid values are: engagements, impressions, ...", "title": "Invalid Sort Property", "type": "ANL_00422" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Invalid request — validation error (`ANL_00400`) or unsupported sort property (`ANL_00422`)" }, "401": { "content": { "application/problem+json": { "examples": { "expired": { "summary": "ANL_00401 — Token expired", "value": { "detail": "The JWT has expired; request a new token via /oauth/token.", "title": "Unauthorized", "type": "ANL_00401" } }, "invalid": { "summary": "ANL_00401 — Missing, malformed or invalid JWT", "value": { "detail": "The authentication token could not be validated. Please ensure your token is valid and try again.", "title": "Unauthorized", "type": "ANL_00401" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authentication failed — the JWT is missing, malformed, invalid, or expired (`ANL_00401`). Request a new token via `POST /oauth/token` before retrying." }, "403": { "content": { "application/problem+json": { "examples": { "forbidden": { "summary": "ANL_00403 — Instance scope not accessible with this token", "value": { "detail": "Access denied. The requested instance IDs are not accessible with this token.", "title": "Forbidden", "type": "ANL_00403" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authorization failed — the JWT is valid but the requested scope is not accessible with this token (`ANL_00403`). Typically one or more `instanceIds` are not bound to the client." }, "500": { "content": { "application/problem+json": { "examples": { "ANL_00500": { "summary": "ANL_00500 — Unexpected server error", "value": { "detail": "An unexpected error occurred while processing the request.", "title": "Internal Error", "type": "ANL_00500" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "An unexpected error occurred while processing the request (`ANL_00500`). The request was not processed and the credentials are not implicated — retry with exponential backoff." } }, "security": [ { "JWT": [] } ], "summary": "Campaign performance metrics", "tags": [ "Campaign Level" ] } }, "/v2/creators/performance": { "get": { "description": "Returns a list of creators with their performance metrics and profile information.\n\n**What is included per creator:**\n- Creator profile (name, picture, social handles across platforms)\n- Metrics requested via the `metrics` query parameter", "operationId": "getCreators", "parameters": [ { "description": "Start of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "startDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-01-01" ] } }, { "description": "End of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "endDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-12-31" ] } }, { "description": "Specify one or more metric names to include in the response. Only the selected metrics will be returned within the `metrics` object for each result item.\n\n**Supported values:**\n`likes`, `comments`, `shares`, `saves`, `impressions`, `reach`, `organicReach`, `engagements`, `views`, `totalInteractions`, `replies`, `reposts`, `potentialReach`, `videoViewTotalTime`, `avgWatchTime`, `navigationTapExit`, `navigationTapBack`, `navigationTapForward`, `navigationSwipeForward`, `crosspostedViews`, `crosspostedFacebookOnlyViews`, `engagementRate`, `postsCount`, `estimatedValueGenerated`, `estimatedContentCost`, `estimatedRoi`, `cpe`, `cpm`, `paidLikes`, `paidComments`, `paidShares`, `paidImpressions`, `paidEngagements`, `paidEngagementRate`, `paidViews`, `paidReach`, `paidSaves`, `paidCpe`, `paidCpm`, `paidPostsCount`, `paidCost`, `trackingLinksClicks`, `trackingLinksConversions`, `trackingLinksConversionValue`, `affiliateLinksClicks`, `affiliateLinksConversions`, `affiliateLinksConversionRate`, `affiliateLinksSales`, `affiliateLinksCommissionEarned`, `affiliateLinksRoi`\n\nMetric availability depends on the applied `platform` or `contentType` filters. Some metrics are restricted to specific content types (for example, `crosspostedFacebookOnlyViews` is only available for Instagram Reels). Requesting unsupported metrics will result in a `400` error, along with a list of valid metrics for the current filters.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "metrics", "required": true, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific instances. When omitted, the request is evaluated against every instance associated with your OAuth client; supply one or more values to narrow the response to a subset. Values must be drawn from the set bound to your client credentials — requesting an instance outside that set returns `403` with `type: ANL_00403`.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "instanceIds", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific campaigns. When omitted, all campaigns are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "campaignIds", "required": false, "schema": { "items": { "type": "number" }, "maxItems": 50, "type": "array" } }, { "description": "Filter by top-level platform. Selecting a platform includes all its content types (e.g. `instagram` includes `instagram_post`, `instagram_reel`, `instagram_story`).\n\nCannot be combined with `contentType` — provide only one of the two.\n\nWhen omitted (and `contentType` is also omitted), all platforms are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "platform", "required": false, "schema": { "items": { "enum": [ "instagram", "tiktok", "facebook", "youtube", "twitter", "linkedin", "pinterest", "snapchat", "blog", "twitch" ], "type": "string" }, "type": "array" } }, { "description": "Filter by specific content type for granular filtering beyond top-level platforms.\n\n- `instagram_post`, `instagram_reel`, `instagram_story` — specific Instagram content formats\n- `facebook_post`, `facebook_live`, `facebook_group`, `facebook_reel` — specific Facebook content formats\n- `tiktok`, `youtube_video`, `youtube_shorts` — platform-specific types\n\nCannot be combined with `platform` — provide only one of the two.\n\nWhen omitted (and `platform` is also omitted), all content types are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "contentType", "required": false, "schema": { "items": { "enum": [ "instagram_post", "instagram_reel", "instagram_story", "facebook_post", "facebook_live", "facebook_group", "facebook_reel", "tiktok", "youtube_video", "youtube_shorts", "twitter", "linkedin", "pinterest", "snapchat_story", "blog", "twitch_stream" ], "type": "string" }, "type": "array" } }, { "description": "Controls which date dimension is used for filtering.\n\n- **`post_date`** (default): filters by the date the content was originally published. Best for analyzing content output and creator activity over time.\n- **`performance_date`**: returns metrics recorded within the requested date range, regardless of when the content was originally published. Best for understanding how campaigns performed during a specific reporting window.\n\nExample: a post published on Jan 5 that receives engagement on Feb 10 will appear in a Feb 1–28 query with `performance_date`, but in a Jan 1–31 query with `post_date`.", "in": "query", "name": "dateBasis", "required": false, "schema": { "default": "post_date", "enum": [ "post_date", "performance_date" ], "type": "string", "examples": [ "post_date" ] } }, { "description": "Maximum number of items to return per page. Choose any value on the first request, then keep it unchanged on every subsequent request that passes a `nextCursor` from this endpoint. To change the page size, start a new walk by omitting `nextCursor`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "number", "examples": [ 50 ] } }, { "description": "Opaque cursor returned by the previous page. Omit on the first request. Cursors are tied to the query parameters of the request that produced them; to paginate, keep every parameter identical across requests and only vary `nextCursor`. To change filters, sort, or `limit`, start a new walk by omitting `nextCursor`.", "in": "query", "name": "nextCursor", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Metric or field name to sort results by. Use `sortDirection` (`ASC` or `DESC`, default: `DESC`) to control the order.\n\n**Supported values:** `likes`, `comments`, `shares`, `saves`, `impressions`, `reach`, `organicReach`, `engagements`, `views`, `totalInteractions`, `replies`, `reposts`, `potentialReach`, `videoViewTotalTime`, `avgWatchTime`, `navigationTapExit`, `navigationTapBack`, `navigationTapForward`, `navigationSwipeForward`, `crosspostedViews`, `crosspostedFacebookOnlyViews`, `engagementRate`, `postsCount`, `estimatedValueGenerated`, `estimatedContentCost`, `estimatedRoi`, `cpe`, `cpm`, `paidLikes`, `paidComments`, `paidShares`, `paidImpressions`, `paidEngagements`, `paidEngagementRate`, `paidViews`, `paidReach`, `paidSaves`, `paidCpe`, `paidCpm`, `paidPostsCount`, `paidCost`, `trackingLinksClicks`, `trackingLinksConversions`, `trackingLinksConversionValue`, `affiliateLinksClicks`, `affiliateLinksConversions`, `affiliateLinksConversionRate`, `affiliateLinksSales`, `affiliateLinksCommissionEarned`, `affiliateLinksRoi`\n\n> **Note:** When `platform` or `contentType` filters are applied, only metrics supported by the selected content types are accepted as sort properties. The API returns an error with the valid list when an unsupported sort property is used with a filter.", "in": "query", "name": "sortProperty", "required": false, "schema": { "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "sortDirection", "required": false, "schema": { "default": "DESC", "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CreatorPerformanceResponseDto" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" }, "examples": { "default": { "value": { "data": [ { "creator": { "creatorId": 12345, "fullName": "Jane Smith", "profilePictureUrl": "https://example.com/profiles/jane.jpg", "profiles": [ { "contentType": "instagram_post", "fullName": "Jane Smith", "handleName": "janesmith", "profileImage": "https://example.com/profiles/jane_ig.jpg", "profileLink": "https://instagram.com/janesmith" }, { "contentType": "tiktok", "fullName": "Jane Smith", "handleName": "janesmithtok", "profileImage": null, "profileLink": "https://tiktok.com/@janesmithtok" } ] }, "metrics": { "affiliateLinksClicks": 540, "affiliateLinksCommissionEarned": 280, "affiliateLinksConversionRate": 5.93, "affiliateLinksConversions": 32, "affiliateLinksRoi": 9, "affiliateLinksSales": 2800, "cpe": 0.3, "cpm": 40.32, "engagementRate": 13.55, "engagements": 8400, "estimatedContentCost": 2500, "estimatedRoi": 7.4, "estimatedValueGenerated": 18500, "impressions": 62000, "paidCost": 1800, "paidCpe": 0.86, "paidCpm": 64.29, "paidEngagementRate": 7.5, "paidEngagements": 2100, "paidImpressions": 28000, "paidPostsCount": 3, "postsCount": 15, "reach": 45000, "trackingLinksClicks": 320, "trackingLinksConversionValue": 4200, "trackingLinksConversions": 18, "views": 32000 } } ], "nextCursor": "eyJ2ZXJzaW9uIjoxfQ" } } } } }, "description": "Creator performance metrics" }, "400": { "content": { "application/problem+json": { "examples": { "ANL_00400": { "summary": "ANL_00400 — Query parameter validation failed", "value": { "detail": "startDate must be a Date instance; endDate must be a Date instance", "title": "Validation Error", "type": "ANL_00400" } }, "ANL_00422": { "summary": "ANL_00422 — Invalid sort property", "value": { "detail": "Invalid sortProperty 'invalidField' for /creators. Valid values are: engagements, impressions, ...", "title": "Invalid Sort Property", "type": "ANL_00422" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Invalid request — validation error (`ANL_00400`) or unsupported sort property (`ANL_00422`)" }, "401": { "content": { "application/problem+json": { "examples": { "expired": { "summary": "ANL_00401 — Token expired", "value": { "detail": "The JWT has expired; request a new token via /oauth/token.", "title": "Unauthorized", "type": "ANL_00401" } }, "invalid": { "summary": "ANL_00401 — Missing, malformed or invalid JWT", "value": { "detail": "The authentication token could not be validated. Please ensure your token is valid and try again.", "title": "Unauthorized", "type": "ANL_00401" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authentication failed — the JWT is missing, malformed, invalid, or expired (`ANL_00401`). Request a new token via `POST /oauth/token` before retrying." }, "403": { "content": { "application/problem+json": { "examples": { "forbidden": { "summary": "ANL_00403 — Instance scope not accessible with this token", "value": { "detail": "Access denied. The requested instance IDs are not accessible with this token.", "title": "Forbidden", "type": "ANL_00403" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authorization failed — the JWT is valid but the requested scope is not accessible with this token (`ANL_00403`). Typically one or more `instanceIds` are not bound to the client." }, "500": { "content": { "application/problem+json": { "examples": { "ANL_00500": { "summary": "ANL_00500 — Unexpected server error", "value": { "detail": "An unexpected error occurred while processing the request.", "title": "Internal Error", "type": "ANL_00500" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "An unexpected error occurred while processing the request (`ANL_00500`). The request was not processed and the credentials are not implicated — retry with exponential backoff." } }, "security": [ { "JWT": [] } ], "summary": "Creator performance metrics", "tags": [ "Creator Level" ] } }, "/v2/instances": { "get": { "description": "Returns the list of instance IDs accessible by your API credentials.\n\nUse this endpoint to discover which instances are available before querying performance data.", "operationId": "getInstances", "parameters": [ { "description": "Maximum number of items to return per page. Choose any value on the first request, then keep it unchanged on every subsequent request that passes a `nextCursor` from this endpoint. To change the page size, start a new walk by omitting `nextCursor`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "number", "examples": [ 50 ] } }, { "description": "Opaque cursor returned by the previous page. Omit on the first request. Cursors are tied to the query parameters of the request that produced them; to paginate, keep every parameter identical across requests and only vary `nextCursor`. To change filters, sort, or `limit`, start a new walk by omitting `nextCursor`.", "in": "query", "name": "nextCursor", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/InstancesListResponseDto" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" }, "examples": { "default": { "value": { "data": { "instanceIds": [ "instance_abc", "instance_def" ] }, "nextCursor": "eyJ2ZXJzaW9uIjoxfQ" } } } } }, "description": "List of instance IDs accessible by the API credentials" }, "400": { "content": { "application/problem+json": { "examples": { "ANL_00400": { "summary": "ANL_00400 — Query parameter validation failed", "value": { "detail": "startDate must be a Date instance; endDate must be a Date instance", "title": "Validation Error", "type": "ANL_00400" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "One or more query parameters failed validation (`ANL_00400`)" }, "401": { "content": { "application/problem+json": { "examples": { "expired": { "summary": "ANL_00401 — Token expired", "value": { "detail": "The JWT has expired; request a new token via /oauth/token.", "title": "Unauthorized", "type": "ANL_00401" } }, "invalid": { "summary": "ANL_00401 — Missing, malformed or invalid JWT", "value": { "detail": "The authentication token could not be validated. Please ensure your token is valid and try again.", "title": "Unauthorized", "type": "ANL_00401" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authentication failed — the JWT is missing, malformed, invalid, or expired (`ANL_00401`). Request a new token via `POST /oauth/token` before retrying." }, "403": { "content": { "application/problem+json": { "examples": { "forbidden": { "summary": "ANL_00403 — Instance scope not accessible with this token", "value": { "detail": "Access denied. The requested instance IDs are not accessible with this token.", "title": "Forbidden", "type": "ANL_00403" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authorization failed — the JWT is valid but the requested scope is not accessible with this token (`ANL_00403`). Typically one or more `instanceIds` are not bound to the client." }, "500": { "content": { "application/problem+json": { "examples": { "ANL_00500": { "summary": "ANL_00500 — Unexpected server error", "value": { "detail": "An unexpected error occurred while processing the request.", "title": "Internal Error", "type": "ANL_00500" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "An unexpected error occurred while processing the request (`ANL_00500`). The request was not processed and the credentials are not implicated — retry with exponential backoff." } }, "security": [ { "JWT": [] } ], "summary": "List accessible instances", "tags": [ "Instance Level" ] } }, "/v2/instances/performance": { "get": { "description": "Returns aggregated performance metrics across all content for the given instances and date range.\n\n**Response shape:**\nMetrics are nested under `data.metrics` so the envelope matches the other reporting endpoints (campaigns, creators, posts, networks) and leaves room to add non-metric top-level fields later without breaking existing clients.\n\n**What is included:**\n- Metrics requested via the `metrics` query parameter (returned inside `data.metrics`)\n\nSupported metric groups:\n- Organic engagement metrics (engagements, impressions, reach, views)\n- Paid media metrics (paid engagements, impressions, ad spend, ROAS)\n- Cost and ROI estimates\n- Tracking link and affiliate link conversion data", "operationId": "getInstancePerformance", "parameters": [ { "description": "Start of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "startDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-01-01" ] } }, { "description": "End of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "endDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-12-31" ] } }, { "description": "Specify one or more metric names to include in the response. Only the selected metrics will be returned within the `metrics` object for each result item.\n\n**Supported values:**\n`engagements`, `impressions`, `engagementRate`, `postsCount`, `reach`, `organicReach`, `views`, `estimatedValueGenerated`, `estimatedContentCost`, `campaignsCost`, `returnOnInvestment`, `cpe`, `cpm`, `paidEngagements`, `paidImpressions`, `paidEngagementRate`, `paidPostsCount`, `paidReach`, `paidViews`, `paidAdSpend`, `paidReturnOnAdSpend`, `paidCpe`, `paidCpm`, `trackingLinksClicks`, `trackingLinksConversions`, `trackingLinksConversionValue`, `affiliateLinksClicks`, `affiliateLinksConversions`, `affiliateLinksSales`\n\nMetric availability depends on the applied `platform` or `contentType` filters. Some metrics are restricted to specific content types (for example, `crosspostedFacebookOnlyViews` is only available for Instagram Reels). Requesting unsupported metrics will result in a `400` error, along with a list of valid metrics for the current filters.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "metrics", "required": true, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific instances. When omitted, the request is evaluated against every instance associated with your OAuth client; supply one or more values to narrow the response to a subset. Values must be drawn from the set bound to your client credentials — requesting an instance outside that set returns `403` with `type: ANL_00403`.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "instanceIds", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific campaigns. When omitted, all campaigns are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "campaignIds", "required": false, "schema": { "items": { "type": "number" }, "maxItems": 50, "type": "array" } }, { "description": "Filter by top-level platform. Selecting a platform includes all its content types (e.g. `instagram` includes `instagram_post`, `instagram_reel`, `instagram_story`).\n\nCannot be combined with `contentType` — provide only one of the two.\n\nWhen omitted (and `contentType` is also omitted), all platforms are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "platform", "required": false, "schema": { "items": { "enum": [ "instagram", "tiktok", "facebook", "youtube", "twitter", "linkedin", "pinterest", "snapchat", "blog", "twitch" ], "type": "string" }, "type": "array" } }, { "description": "Filter by specific content type for granular filtering beyond top-level platforms.\n\n- `instagram_post`, `instagram_reel`, `instagram_story` — specific Instagram content formats\n- `facebook_post`, `facebook_live`, `facebook_group`, `facebook_reel` — specific Facebook content formats\n- `tiktok`, `youtube_video`, `youtube_shorts` — platform-specific types\n\nCannot be combined with `platform` — provide only one of the two.\n\nWhen omitted (and `platform` is also omitted), all content types are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "contentType", "required": false, "schema": { "items": { "enum": [ "instagram_post", "instagram_reel", "instagram_story", "facebook_post", "facebook_live", "facebook_group", "facebook_reel", "tiktok", "youtube_video", "youtube_shorts", "twitter", "linkedin", "pinterest", "snapchat_story", "blog", "twitch_stream" ], "type": "string" }, "type": "array" } }, { "description": "Controls which date dimension is used for filtering.\n\n- **`post_date`** (default): filters by the date the content was originally published. Best for analyzing content output and creator activity over time.\n- **`performance_date`**: returns metrics recorded within the requested date range, regardless of when the content was originally published. Best for understanding how campaigns performed during a specific reporting window.\n\nExample: a post published on Jan 5 that receives engagement on Feb 10 will appear in a Feb 1–28 query with `performance_date`, but in a Jan 1–31 query with `post_date`.", "in": "query", "name": "dateBasis", "required": false, "schema": { "default": "post_date", "enum": [ "post_date", "performance_date" ], "type": "string", "examples": [ "post_date" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PerformanceSummaryResponseDto" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" }, "examples": { "default": { "value": { "data": { "metrics": { "affiliateLinksClicks": 3400, "affiliateLinksConversions": 210, "affiliateLinksSales": 18500, "campaignsCost": 15000, "cpe": 0.33, "cpm": 48.08, "engagementRate": 14.49, "engagements": 45200, "estimatedContentCost": 15000, "estimatedValueGenerated": 125000, "impressions": 312000, "organicReach": 240000, "paidAdSpend": 8500, "paidCpe": 0.66, "paidCpm": 45.95, "paidEngagementRate": 6.92, "paidEngagements": 12800, "paidImpressions": 185000, "paidPostsCount": 18, "paidReach": 65000, "paidReturnOnAdSpend": 3.8, "paidViews": 42000, "postsCount": 142, "reach": 280000, "returnOnInvestment": 8.33, "trackingLinksClicks": 1200, "trackingLinksConversionValue": 42000, "trackingLinksConversions": 85, "views": 95000 } }, "nextCursor": null } } } } }, "description": "Aggregated performance summary" }, "400": { "content": { "application/problem+json": { "examples": { "ANL_00400": { "summary": "ANL_00400 — Query parameter validation failed", "value": { "detail": "startDate must be a Date instance; endDate must be a Date instance", "title": "Validation Error", "type": "ANL_00400" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "One or more query parameters failed validation (`ANL_00400`)" }, "401": { "content": { "application/problem+json": { "examples": { "expired": { "summary": "ANL_00401 — Token expired", "value": { "detail": "The JWT has expired; request a new token via /oauth/token.", "title": "Unauthorized", "type": "ANL_00401" } }, "invalid": { "summary": "ANL_00401 — Missing, malformed or invalid JWT", "value": { "detail": "The authentication token could not be validated. Please ensure your token is valid and try again.", "title": "Unauthorized", "type": "ANL_00401" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authentication failed — the JWT is missing, malformed, invalid, or expired (`ANL_00401`). Request a new token via `POST /oauth/token` before retrying." }, "403": { "content": { "application/problem+json": { "examples": { "forbidden": { "summary": "ANL_00403 — Instance scope not accessible with this token", "value": { "detail": "Access denied. The requested instance IDs are not accessible with this token.", "title": "Forbidden", "type": "ANL_00403" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authorization failed — the JWT is valid but the requested scope is not accessible with this token (`ANL_00403`). Typically one or more `instanceIds` are not bound to the client." }, "500": { "content": { "application/problem+json": { "examples": { "ANL_00500": { "summary": "ANL_00500 — Unexpected server error", "value": { "detail": "An unexpected error occurred while processing the request.", "title": "Internal Error", "type": "ANL_00500" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "An unexpected error occurred while processing the request (`ANL_00500`). The request was not processed and the credentials are not implicated — retry with exponential backoff." } }, "security": [ { "JWT": [] } ], "summary": "Instance performance summary", "tags": [ "Instance Level" ] } }, "/v2/instances/performance-over-time": { "get": { "description": "Returns time-series performance metrics for the given instances, broken into time buckets.\n\n**What is included per time bucket:**\n- Metrics requested via the `metrics` query parameter\n- Each data point includes `startDate` (inclusive) and `endDate` (inclusive) indicating the bucket boundaries\n\nUse the `granularity` parameter to control the bucket size.\n\n**Gaps in the response:**\nThe response can contain gaps — time buckets with no activity for the selected instances, filters, and date range are omitted from the `data` array rather than returned as zero-filled entries. For example, a `month` granularity request spanning six months may return fewer than six data points if some months had no posts, impressions, or paid spend for the given filters. Clients that need a contiguous series should fill missing buckets locally using the requested `startDate` / `endDate` range and `granularity`.", "operationId": "getInstancePerformanceOverTime", "parameters": [ { "description": "Start of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "startDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-01-01" ] } }, { "description": "End of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "endDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-12-31" ] } }, { "description": "Specify one or more metric names to include in the response. Only the selected metrics will be returned within the `metrics` object for each result item.\n\n**Supported values:**\n`likes`, `comments`, `shares`, `clicks`, `impressions`, `reach`, `organicReach`, `engagements`, `views`, `engagementRate`, `postsCount`, `estimatedValueGenerated`, `cpe`, `cpm`, `paidLikes`, `paidComments`, `paidShares`, `paidImpressions`, `paidEngagements`, `paidEngagementRate`, `paidReach`, `paidViews`\n\nMetric availability depends on the applied `platform` or `contentType` filters. Some metrics are restricted to specific content types (for example, `crosspostedFacebookOnlyViews` is only available for Instagram Reels). Requesting unsupported metrics will result in a `400` error, along with a list of valid metrics for the current filters.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "metrics", "required": true, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific instances. When omitted, the request is evaluated against every instance associated with your OAuth client; supply one or more values to narrow the response to a subset. Values must be drawn from the set bound to your client credentials — requesting an instance outside that set returns `403` with `type: ANL_00403`.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "instanceIds", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific campaigns. When omitted, all campaigns are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "campaignIds", "required": false, "schema": { "items": { "type": "number" }, "maxItems": 50, "type": "array" } }, { "description": "Filter by top-level platform. Selecting a platform includes all its content types (e.g. `instagram` includes `instagram_post`, `instagram_reel`, `instagram_story`).\n\nCannot be combined with `contentType` — provide only one of the two.\n\nWhen omitted (and `contentType` is also omitted), all platforms are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "platform", "required": false, "schema": { "items": { "enum": [ "instagram", "tiktok", "facebook", "youtube", "twitter", "linkedin", "pinterest", "snapchat", "blog", "twitch" ], "type": "string" }, "type": "array" } }, { "description": "Filter by specific content type for granular filtering beyond top-level platforms.\n\n- `instagram_post`, `instagram_reel`, `instagram_story` — specific Instagram content formats\n- `facebook_post`, `facebook_live`, `facebook_group`, `facebook_reel` — specific Facebook content formats\n- `tiktok`, `youtube_video`, `youtube_shorts` — platform-specific types\n\nCannot be combined with `platform` — provide only one of the two.\n\nWhen omitted (and `platform` is also omitted), all content types are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "contentType", "required": false, "schema": { "items": { "enum": [ "instagram_post", "instagram_reel", "instagram_story", "facebook_post", "facebook_live", "facebook_group", "facebook_reel", "tiktok", "youtube_video", "youtube_shorts", "twitter", "linkedin", "pinterest", "snapchat_story", "blog", "twitch_stream" ], "type": "string" }, "type": "array" } }, { "description": "Controls which date dimension is used for filtering.\n\n- **`post_date`** (default): filters by the date the content was originally published. Best for analyzing content output and creator activity over time.\n- **`performance_date`**: returns metrics recorded within the requested date range, regardless of when the content was originally published. Best for understanding how campaigns performed during a specific reporting window.\n\nExample: a post published on Jan 5 that receives engagement on Feb 10 will appear in a Feb 1–28 query with `performance_date`, but in a Jan 1–31 query with `post_date`.", "in": "query", "name": "dateBasis", "required": false, "schema": { "default": "post_date", "enum": [ "post_date", "performance_date" ], "type": "string", "examples": [ "post_date" ] } }, { "description": "Maximum number of items to return per page. Choose any value on the first request, then keep it unchanged on every subsequent request that passes a `nextCursor` from this endpoint. To change the page size, start a new walk by omitting `nextCursor`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "number", "examples": [ 50 ] } }, { "description": "Opaque cursor returned by the previous page. Omit on the first request. Cursors are tied to the query parameters of the request that produced them; to paginate, keep every parameter identical across requests and only vary `nextCursor`. To change filters, sort, or `limit`, start a new walk by omitting `nextCursor`.", "in": "query", "name": "nextCursor", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Controls the time bucket size for the timeseries data.\n\n| Value | Behavior |\n|-------|----------|\n| `day` | One bucket per calendar day |\n| `week` | Aggregates by ISO 8601 week (Monday–Sunday) |\n| `month` | Aggregates by calendar month (1st–last day) |\n| `quarter` | Aggregates by calendar quarter (Q1 = Jan–Mar, Q2 = Apr–Jun, Q3 = Jul–Sep, Q4 = Oct–Dec) |\n| `year` | Aggregates by calendar year (Jan 1–Dec 31) |\n\nEach data point includes `startDate` (inclusive) and `endDate` (inclusive) indicating the bucket boundaries. Partial buckets are returned at the edges of the requested date range.\n\nBuckets with no activity for the selected instances, filters, and date range are omitted from the response — the returned series can therefore contain gaps. For example, a `month`-granularity request over six months may return fewer than six data points if some months had no posts, impressions, or paid spend. Clients that need a contiguous series should fill missing buckets locally from the requested date range and granularity.", "in": "query", "name": "granularity", "required": false, "schema": { "default": "month", "enum": [ "year", "quarter", "month", "week", "day" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TimeseriesDataPointDto" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" }, "examples": { "default": { "value": { "data": [ { "endDate": "2024-01-31", "metrics": { "clicks": 560, "comments": 340, "cpe": 0.29, "cpm": 35.14, "engagementRate": 12.32, "engagements": 2280, "estimatedValueGenerated": 8200, "impressions": 18500, "likes": 1200, "organicReach": 12800, "paidComments": 85, "paidEngagementRate": 7.88, "paidEngagements": 945, "paidImpressions": 12000, "paidLikes": 400, "paidReach": 9400, "paidShares": 60, "paidViews": 7200, "postsCount": 8, "reach": 14200, "shares": 180, "views": 9800 }, "startDate": "2024-01-01" }, { "endDate": "2024-02-29", "metrics": { "clicks": 620, "comments": 390, "cpe": 0.27, "cpm": 33.81, "engagementRate": 12.71, "engagements": 2670, "estimatedValueGenerated": 9400, "impressions": 21000, "likes": 1450, "organicReach": 12800, "paidComments": 110, "paidEngagementRate": 7.78, "paidEngagements": 1105, "paidImpressions": 14200, "paidLikes": 520, "paidReach": 10800, "paidShares": 75, "paidViews": 8400, "postsCount": 9, "reach": 16100, "shares": 210, "views": 11200 }, "startDate": "2024-02-01" } ], "nextCursor": "eyJ2ZXJzaW9uIjoxfQ" } } } } }, "description": "Timeseries performance data" }, "400": { "content": { "application/problem+json": { "examples": { "ANL_00400": { "summary": "ANL_00400 — Query parameter validation failed", "value": { "detail": "startDate must be a Date instance; endDate must be a Date instance", "title": "Validation Error", "type": "ANL_00400" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "One or more query parameters failed validation (`ANL_00400`)" }, "401": { "content": { "application/problem+json": { "examples": { "expired": { "summary": "ANL_00401 — Token expired", "value": { "detail": "The JWT has expired; request a new token via /oauth/token.", "title": "Unauthorized", "type": "ANL_00401" } }, "invalid": { "summary": "ANL_00401 — Missing, malformed or invalid JWT", "value": { "detail": "The authentication token could not be validated. Please ensure your token is valid and try again.", "title": "Unauthorized", "type": "ANL_00401" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authentication failed — the JWT is missing, malformed, invalid, or expired (`ANL_00401`). Request a new token via `POST /oauth/token` before retrying." }, "403": { "content": { "application/problem+json": { "examples": { "forbidden": { "summary": "ANL_00403 — Instance scope not accessible with this token", "value": { "detail": "Access denied. The requested instance IDs are not accessible with this token.", "title": "Forbidden", "type": "ANL_00403" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authorization failed — the JWT is valid but the requested scope is not accessible with this token (`ANL_00403`). Typically one or more `instanceIds` are not bound to the client." }, "500": { "content": { "application/problem+json": { "examples": { "ANL_00500": { "summary": "ANL_00500 — Unexpected server error", "value": { "detail": "An unexpected error occurred while processing the request.", "title": "Internal Error", "type": "ANL_00500" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "An unexpected error occurred while processing the request (`ANL_00500`). The request was not processed and the credentials are not implicated — retry with exponential backoff." } }, "security": [ { "JWT": [] } ], "summary": "Instance performance over time", "tags": [ "Instance Level" ] } }, "/v2/platforms/performance": { "get": { "description": "Returns performance metrics grouped by content type (e.g. instagram_post, instagram_reel, tiktok, facebook_post).\n\n**What is included per content type:**\n- The `contentType` identifier\n- Metrics requested via the `metrics` query parameter", "operationId": "getNetworks", "parameters": [ { "description": "Start of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "startDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-01-01" ] } }, { "description": "End of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "endDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-12-31" ] } }, { "description": "Specify one or more metric names to include in the response. Only the selected metrics will be returned within the `metrics` object for each result item.\n\n**Supported values:**\n`likes`, `comments`, `shares`, `saves`, `impressions`, `reach`, `organicReach`, `engagements`, `views`, `totalInteractions`, `replies`, `reposts`, `potentialReach`, `videoViewTotalTime`, `avgWatchTime`, `navigationTapExit`, `navigationTapBack`, `navigationTapForward`, `navigationSwipeForward`, `crosspostedViews`, `crosspostedFacebookOnlyViews`, `engagementRate`, `postsCount`, `impressionsPerPost`, `engagementsPerPost`, `estimatedValueGenerated`, `cpe`, `cpm`, `paidLikes`, `paidComments`, `paidShares`, `paidImpressions`, `paidEngagements`, `paidEngagementRate`, `paidViews`, `paidReach`, `paidSaves`, `paidCpe`, `paidCpm`, `paidPostsCount`, `paidAdSpend`, `paidReturnOnAdSpend`\n\nMetric availability depends on the applied `platform` or `contentType` filters. Some metrics are restricted to specific content types (for example, `crosspostedFacebookOnlyViews` is only available for Instagram Reels). Requesting unsupported metrics will result in a `400` error, along with a list of valid metrics for the current filters.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "metrics", "required": true, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific instances. When omitted, the request is evaluated against every instance associated with your OAuth client; supply one or more values to narrow the response to a subset. Values must be drawn from the set bound to your client credentials — requesting an instance outside that set returns `403` with `type: ANL_00403`.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "instanceIds", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific campaigns. When omitted, all campaigns are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "campaignIds", "required": false, "schema": { "items": { "type": "number" }, "maxItems": 50, "type": "array" } }, { "description": "Filter by top-level platform. Selecting a platform includes all its content types (e.g. `instagram` includes `instagram_post`, `instagram_reel`, `instagram_story`).\n\nCannot be combined with `contentType` — provide only one of the two.\n\nWhen omitted (and `contentType` is also omitted), all platforms are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "platform", "required": false, "schema": { "items": { "enum": [ "instagram", "tiktok", "facebook", "youtube", "twitter", "linkedin", "pinterest", "snapchat", "blog", "twitch" ], "type": "string" }, "type": "array" } }, { "description": "Filter by specific content type for granular filtering beyond top-level platforms.\n\n- `instagram_post`, `instagram_reel`, `instagram_story` — specific Instagram content formats\n- `facebook_post`, `facebook_live`, `facebook_group`, `facebook_reel` — specific Facebook content formats\n- `tiktok`, `youtube_video`, `youtube_shorts` — platform-specific types\n\nCannot be combined with `platform` — provide only one of the two.\n\nWhen omitted (and `platform` is also omitted), all content types are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "contentType", "required": false, "schema": { "items": { "enum": [ "instagram_post", "instagram_reel", "instagram_story", "facebook_post", "facebook_live", "facebook_group", "facebook_reel", "tiktok", "youtube_video", "youtube_shorts", "twitter", "linkedin", "pinterest", "snapchat_story", "blog", "twitch_stream" ], "type": "string" }, "type": "array" } }, { "description": "Controls which date dimension is used for filtering.\n\n- **`post_date`** (default): filters by the date the content was originally published. Best for analyzing content output and creator activity over time.\n- **`performance_date`**: returns metrics recorded within the requested date range, regardless of when the content was originally published. Best for understanding how campaigns performed during a specific reporting window.\n\nExample: a post published on Jan 5 that receives engagement on Feb 10 will appear in a Feb 1–28 query with `performance_date`, but in a Jan 1–31 query with `post_date`.", "in": "query", "name": "dateBasis", "required": false, "schema": { "default": "post_date", "enum": [ "post_date", "performance_date" ], "type": "string", "examples": [ "post_date" ] } }, { "description": "Maximum number of items to return per page. Choose any value on the first request, then keep it unchanged on every subsequent request that passes a `nextCursor` from this endpoint. To change the page size, start a new walk by omitting `nextCursor`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "number", "examples": [ 50 ] } }, { "description": "Opaque cursor returned by the previous page. Omit on the first request. Cursors are tied to the query parameters of the request that produced them; to paginate, keep every parameter identical across requests and only vary `nextCursor`. To change filters, sort, or `limit`, start a new walk by omitting `nextCursor`.", "in": "query", "name": "nextCursor", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Metric or field name to sort results by. Use `sortDirection` (`ASC` or `DESC`, default: `DESC`) to control the order.\n\n**Supported values:** `likes`, `comments`, `shares`, `saves`, `impressions`, `reach`, `organicReach`, `engagements`, `views`, `totalInteractions`, `replies`, `reposts`, `potentialReach`, `videoViewTotalTime`, `avgWatchTime`, `navigationTapExit`, `navigationTapBack`, `navigationTapForward`, `navigationSwipeForward`, `crosspostedViews`, `crosspostedFacebookOnlyViews`, `engagementRate`, `postsCount`, `impressionsPerPost`, `engagementsPerPost`, `estimatedValueGenerated`, `cpe`, `cpm`, `paidLikes`, `paidComments`, `paidShares`, `paidImpressions`, `paidEngagements`, `paidEngagementRate`, `paidViews`, `paidReach`, `paidSaves`, `paidCpe`, `paidCpm`, `paidPostsCount`, `paidAdSpend`, `paidReturnOnAdSpend`\n\n> **Note:** When `platform` or `contentType` filters are applied, only metrics supported by the selected content types are accepted as sort properties. The API returns an error with the valid list when an unsupported sort property is used with a filter.", "in": "query", "name": "sortProperty", "required": false, "schema": { "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "sortDirection", "required": false, "schema": { "default": "DESC", "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/NetworkPerformanceResponseDto" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" }, "examples": { "default": { "value": { "data": [ { "contentType": "instagram_post", "metrics": { "engagementRate": 13.03, "engagements": 18500, "engagementsPerPost": 217.65, "impressions": 142000, "impressionsPerPost": 1670.59, "paidEngagementRate": 7.29, "paidEngagements": 6200, "paidImpressions": 85000, "paidPostsCount": 10, "postsCount": 85 } }, { "contentType": "tiktok", "metrics": { "engagementRate": 13.05, "engagements": 12400, "engagementsPerPost": 387.5, "impressions": 95000, "impressionsPerPost": 2968.75, "paidEngagementRate": 6.61, "paidEngagements": 4100, "paidImpressions": 62000, "paidPostsCount": 5, "postsCount": 32 } } ], "nextCursor": "eyJ2ZXJzaW9uIjoxfQ" } } } } }, "description": "Per-platform performance metrics" }, "400": { "content": { "application/problem+json": { "examples": { "ANL_00400": { "summary": "ANL_00400 — Query parameter validation failed", "value": { "detail": "startDate must be a Date instance; endDate must be a Date instance", "title": "Validation Error", "type": "ANL_00400" } }, "ANL_00422": { "summary": "ANL_00422 — Invalid sort property", "value": { "detail": "Invalid sortProperty 'invalidField' for /creators. Valid values are: engagements, impressions, ...", "title": "Invalid Sort Property", "type": "ANL_00422" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Invalid request — validation error (`ANL_00400`) or unsupported sort property (`ANL_00422`)" }, "401": { "content": { "application/problem+json": { "examples": { "expired": { "summary": "ANL_00401 — Token expired", "value": { "detail": "The JWT has expired; request a new token via /oauth/token.", "title": "Unauthorized", "type": "ANL_00401" } }, "invalid": { "summary": "ANL_00401 — Missing, malformed or invalid JWT", "value": { "detail": "The authentication token could not be validated. Please ensure your token is valid and try again.", "title": "Unauthorized", "type": "ANL_00401" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authentication failed — the JWT is missing, malformed, invalid, or expired (`ANL_00401`). Request a new token via `POST /oauth/token` before retrying." }, "403": { "content": { "application/problem+json": { "examples": { "forbidden": { "summary": "ANL_00403 — Instance scope not accessible with this token", "value": { "detail": "Access denied. The requested instance IDs are not accessible with this token.", "title": "Forbidden", "type": "ANL_00403" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authorization failed — the JWT is valid but the requested scope is not accessible with this token (`ANL_00403`). Typically one or more `instanceIds` are not bound to the client." }, "500": { "content": { "application/problem+json": { "examples": { "ANL_00500": { "summary": "ANL_00500 — Unexpected server error", "value": { "detail": "An unexpected error occurred while processing the request.", "title": "Internal Error", "type": "ANL_00500" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "An unexpected error occurred while processing the request (`ANL_00500`). The request was not processed and the credentials are not implicated — retry with exponential backoff." } }, "security": [ { "JWT": [] } ], "summary": "Per-platform performance breakdown", "tags": [ "Platform Level" ] } }, "/v2/platforms/return-on-investment": { "get": { "description": "Returns return-on-investment metrics grouped by content type.\n\n**What is included per content type:**\n- Estimated media value breakdown: value of likes, comments, shares, impressions\n- Total value generated and estimated content cost\n- Return on investment ratio", "operationId": "getNetworksReturnOnInvestment", "parameters": [ { "description": "Start of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "startDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-01-01" ] } }, { "description": "End of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "endDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-12-31" ] } }, { "description": "Filter results to specific instances. When omitted, the request is evaluated against every instance associated with your OAuth client; supply one or more values to narrow the response to a subset. Values must be drawn from the set bound to your client credentials — requesting an instance outside that set returns `403` with `type: ANL_00403`.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "instanceIds", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific campaigns. When omitted, all campaigns are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "campaignIds", "required": false, "schema": { "items": { "type": "number" }, "maxItems": 50, "type": "array" } }, { "description": "Filter by top-level platform. Selecting a platform includes all its content types (e.g. `instagram` includes `instagram_post`, `instagram_reel`, `instagram_story`).\n\nCannot be combined with `contentType` — provide only one of the two.\n\nWhen omitted (and `contentType` is also omitted), all platforms are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "platform", "required": false, "schema": { "items": { "enum": [ "instagram", "tiktok", "facebook", "youtube", "twitter", "linkedin", "pinterest", "snapchat", "blog", "twitch" ], "type": "string" }, "type": "array" } }, { "description": "Filter by specific content type for granular filtering beyond top-level platforms.\n\n- `instagram_post`, `instagram_reel`, `instagram_story` — specific Instagram content formats\n- `facebook_post`, `facebook_live`, `facebook_group`, `facebook_reel` — specific Facebook content formats\n- `tiktok`, `youtube_video`, `youtube_shorts` — platform-specific types\n\nCannot be combined with `platform` — provide only one of the two.\n\nWhen omitted (and `platform` is also omitted), all content types are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "contentType", "required": false, "schema": { "items": { "enum": [ "instagram_post", "instagram_reel", "instagram_story", "facebook_post", "facebook_live", "facebook_group", "facebook_reel", "tiktok", "youtube_video", "youtube_shorts", "twitter", "linkedin", "pinterest", "snapchat_story", "blog", "twitch_stream" ], "type": "string" }, "type": "array" } }, { "description": "Controls which date dimension is used for filtering.\n\n- **`post_date`** (default): filters by the date the content was originally published. Best for analyzing content output and creator activity over time.\n- **`performance_date`**: returns metrics recorded within the requested date range, regardless of when the content was originally published. Best for understanding how campaigns performed during a specific reporting window.\n\nExample: a post published on Jan 5 that receives engagement on Feb 10 will appear in a Feb 1–28 query with `performance_date`, but in a Jan 1–31 query with `post_date`.", "in": "query", "name": "dateBasis", "required": false, "schema": { "default": "post_date", "enum": [ "post_date", "performance_date" ], "type": "string", "examples": [ "post_date" ] } }, { "description": "Maximum number of items to return per page. Choose any value on the first request, then keep it unchanged on every subsequent request that passes a `nextCursor` from this endpoint. To change the page size, start a new walk by omitting `nextCursor`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "number", "examples": [ 50 ] } }, { "description": "Opaque cursor returned by the previous page. Omit on the first request. Cursors are tied to the query parameters of the request that produced them; to paginate, keep every parameter identical across requests and only vary `nextCursor`. To change filters, sort, or `limit`, start a new walk by omitting `nextCursor`.", "in": "query", "name": "nextCursor", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/NetworkRoiResponseDto" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" }, "examples": { "default": { "value": { "data": [ { "contentType": "instagram_post", "estimatedContentCost": 5000, "returnOnInvestment": 5.42, "valueGenerated": 27100, "valueOfComments": 5100, "valueOfImpressions": 14200, "valueOfLikes": 4600, "valueOfShares": 3200 }, { "contentType": "tiktok", "estimatedContentCost": 3500, "returnOnInvestment": 6.26, "valueGenerated": 21900, "valueOfComments": 3400, "valueOfImpressions": 9500, "valueOfLikes": 6200, "valueOfShares": 2800 } ], "nextCursor": "eyJ2ZXJzaW9uIjoxfQ" } } } } }, "description": "Per-platform ROI breakdown" }, "400": { "content": { "application/problem+json": { "examples": { "ANL_00400": { "summary": "ANL_00400 — Query parameter validation failed", "value": { "detail": "startDate must be a Date instance; endDate must be a Date instance", "title": "Validation Error", "type": "ANL_00400" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "One or more query parameters failed validation (`ANL_00400`)" }, "401": { "content": { "application/problem+json": { "examples": { "expired": { "summary": "ANL_00401 — Token expired", "value": { "detail": "The JWT has expired; request a new token via /oauth/token.", "title": "Unauthorized", "type": "ANL_00401" } }, "invalid": { "summary": "ANL_00401 — Missing, malformed or invalid JWT", "value": { "detail": "The authentication token could not be validated. Please ensure your token is valid and try again.", "title": "Unauthorized", "type": "ANL_00401" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authentication failed — the JWT is missing, malformed, invalid, or expired (`ANL_00401`). Request a new token via `POST /oauth/token` before retrying." }, "403": { "content": { "application/problem+json": { "examples": { "forbidden": { "summary": "ANL_00403 — Instance scope not accessible with this token", "value": { "detail": "Access denied. The requested instance IDs are not accessible with this token.", "title": "Forbidden", "type": "ANL_00403" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authorization failed — the JWT is valid but the requested scope is not accessible with this token (`ANL_00403`). Typically one or more `instanceIds` are not bound to the client." }, "500": { "content": { "application/problem+json": { "examples": { "ANL_00500": { "summary": "ANL_00500 — Unexpected server error", "value": { "detail": "An unexpected error occurred while processing the request.", "title": "Internal Error", "type": "ANL_00500" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "An unexpected error occurred while processing the request (`ANL_00500`). The request was not processed and the credentials are not implicated — retry with exponential backoff." } }, "security": [ { "JWT": [] } ], "summary": "Per-platform ROI breakdown", "tags": [ "Platform Level" ] } }, "/v2/posts/performance": { "get": { "description": "Returns a list of individual posts with their performance metrics.\n\n**What is included per post:**\n- Post metadata (ID, date, content type, content URL, image URL)\n- Creator profile information\n- Metrics requested via the `metrics` query parameter\n\nAll posts within the requested date range are returned, including those with zero metric values.", "operationId": "getPosts", "parameters": [ { "description": "Start of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "startDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-01-01" ] } }, { "description": "End of the reporting period (inclusive). Format: `YYYY-MM-DD`.", "in": "query", "name": "endDate", "required": true, "schema": { "format": "date-time", "type": "string", "examples": [ "2025-12-31" ] } }, { "description": "Specify one or more metric names to include in the response. Only the selected metrics will be returned within the `metrics` object for each result item.\n\n**Supported values:**\n`likes`, `comments`, `shares`, `saves`, `impressions`, `reach`, `organicReach`, `engagements`, `views`, `totalInteractions`, `replies`, `reposts`, `potentialReach`, `followersAtPostDate`, `videoViewTotalTime`, `avgWatchTime`, `navigationTapExit`, `navigationTapBack`, `navigationTapForward`, `navigationSwipeForward`, `crosspostedViews`, `crosspostedFacebookOnlyViews`, `engagementRate`, `estimatedValueGenerated`, `cpe`, `cpm`, `paidLikes`, `paidComments`, `paidShares`, `paidImpressions`, `paidEngagements`, `paidEngagementRate`, `paidViews`, `paidReach`, `paidSaves`, `paidCpe`, `paidCpm`\n\nMetric availability depends on the applied `platform` or `contentType` filters. Some metrics are restricted to specific content types (for example, `crosspostedFacebookOnlyViews` is only available for Instagram Reels). Requesting unsupported metrics will result in a `400` error, along with a list of valid metrics for the current filters.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "metrics", "required": true, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific instances. When omitted, the request is evaluated against every instance associated with your OAuth client; supply one or more values to narrow the response to a subset. Values must be drawn from the set bound to your client credentials — requesting an instance outside that set returns `403` with `type: ANL_00403`.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "instanceIds", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter results to specific campaigns. When omitted, all campaigns are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "campaignIds", "required": false, "schema": { "items": { "type": "number" }, "maxItems": 50, "type": "array" } }, { "description": "Filter by top-level platform. Selecting a platform includes all its content types (e.g. `instagram` includes `instagram_post`, `instagram_reel`, `instagram_story`).\n\nCannot be combined with `contentType` — provide only one of the two.\n\nWhen omitted (and `contentType` is also omitted), all platforms are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "platform", "required": false, "schema": { "items": { "enum": [ "instagram", "tiktok", "facebook", "youtube", "twitter", "linkedin", "pinterest", "snapchat", "blog", "twitch" ], "type": "string" }, "type": "array" } }, { "description": "Filter by specific content type for granular filtering beyond top-level platforms.\n\n- `instagram_post`, `instagram_reel`, `instagram_story` — specific Instagram content formats\n- `facebook_post`, `facebook_live`, `facebook_group`, `facebook_reel` — specific Facebook content formats\n- `tiktok`, `youtube_video`, `youtube_shorts` — platform-specific types\n\nCannot be combined with `platform` — provide only one of the two.\n\nWhen omitted (and `platform` is also omitted), all content types are included.\n\nSupported array formats: `param=a,b,c` (comma-separated), `param=a¶m=b` (repeated key), or `param[]=a¶m[]=b` (bracket syntax).", "in": "query", "name": "contentType", "required": false, "schema": { "items": { "enum": [ "instagram_post", "instagram_reel", "instagram_story", "facebook_post", "facebook_live", "facebook_group", "facebook_reel", "tiktok", "youtube_video", "youtube_shorts", "twitter", "linkedin", "pinterest", "snapchat_story", "blog", "twitch_stream" ], "type": "string" }, "type": "array" } }, { "description": "Controls which date dimension is used for filtering.\n\n- **`post_date`** (default): filters by the date the content was originally published. Best for analyzing content output and creator activity over time.\n- **`performance_date`**: returns metrics recorded within the requested date range, regardless of when the content was originally published. Best for understanding how campaigns performed during a specific reporting window.\n\nExample: a post published on Jan 5 that receives engagement on Feb 10 will appear in a Feb 1–28 query with `performance_date`, but in a Jan 1–31 query with `post_date`.", "in": "query", "name": "dateBasis", "required": false, "schema": { "default": "post_date", "enum": [ "post_date", "performance_date" ], "type": "string", "examples": [ "post_date" ] } }, { "description": "Maximum number of items to return per page. Choose any value on the first request, then keep it unchanged on every subsequent request that passes a `nextCursor` from this endpoint. To change the page size, start a new walk by omitting `nextCursor`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "number", "examples": [ 50 ] } }, { "description": "Opaque cursor returned by the previous page. Omit on the first request. Cursors are tied to the query parameters of the request that produced them; to paginate, keep every parameter identical across requests and only vary `nextCursor`. To change filters, sort, or `limit`, start a new walk by omitting `nextCursor`.", "in": "query", "name": "nextCursor", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Metric or field name to sort results by. Use `sortDirection` (`ASC` or `DESC`, default: `DESC`) to control the order.\n\n**Supported values:** `likes`, `comments`, `shares`, `saves`, `impressions`, `reach`, `organicReach`, `engagements`, `views`, `totalInteractions`, `replies`, `reposts`, `potentialReach`, `followersAtPostDate`, `videoViewTotalTime`, `avgWatchTime`, `navigationTapExit`, `navigationTapBack`, `navigationTapForward`, `navigationSwipeForward`, `crosspostedViews`, `crosspostedFacebookOnlyViews`, `engagementRate`, `estimatedValueGenerated`, `cpe`, `cpm`, `paidLikes`, `paidComments`, `paidShares`, `paidImpressions`, `paidEngagements`, `paidEngagementRate`, `paidViews`, `paidReach`, `paidSaves`, `paidCpe`, `paidCpm`, `postDate`\n\n> **Note:** When `platform` or `contentType` filters are applied, only metrics supported by the selected content types are accepted as sort properties. The API returns an error with the valid list when an unsupported sort property is used with a filter.", "in": "query", "name": "sortProperty", "required": false, "schema": { "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "sortDirection", "required": false, "schema": { "default": "DESC", "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PostPerformanceResponseDto" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" }, "examples": { "default": { "value": { "data": [ { "campaignId": 49761, "contentImageUrl": "https://example.com/posts/abc123.jpg", "contentType": "instagram_post", "contentUrl": "https://www.instagram.com/p/ABC123/", "creatorId": 12345, "creatorProfile": { "contentType": "instagram_post", "fullName": "Jane Smith", "handleName": "janesmith", "profileImage": "https://example.com/profiles/jane_ig.jpg", "profileLink": "https://instagram.com/janesmith" }, "instanceId": "instance_abc", "metrics": { "cpe": 0.24, "cpm": 35.29, "engagementRate": 14.59, "engagements": 1240, "estimatedValueGenerated": 3200, "impressions": 8500, "paidCpe": 0.79, "paidCpm": 57.69, "paidEngagementRate": 7.31, "paidEngagements": 380, "paidImpressions": 5200 }, "postDate": "2024-07-15T14:30:00.000Z", "postId": 1234 } ], "nextCursor": "eyJ2ZXJzaW9uIjoxfQ" } } } } }, "description": "Post performance metrics" }, "400": { "content": { "application/problem+json": { "examples": { "ANL_00400": { "summary": "ANL_00400 — Query parameter validation failed", "value": { "detail": "startDate must be a Date instance; endDate must be a Date instance", "title": "Validation Error", "type": "ANL_00400" } }, "ANL_00422": { "summary": "ANL_00422 — Invalid sort property", "value": { "detail": "Invalid sortProperty 'invalidField' for /creators. Valid values are: engagements, impressions, ...", "title": "Invalid Sort Property", "type": "ANL_00422" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Invalid request — validation error (`ANL_00400`) or unsupported sort property (`ANL_00422`)" }, "401": { "content": { "application/problem+json": { "examples": { "expired": { "summary": "ANL_00401 — Token expired", "value": { "detail": "The JWT has expired; request a new token via /oauth/token.", "title": "Unauthorized", "type": "ANL_00401" } }, "invalid": { "summary": "ANL_00401 — Missing, malformed or invalid JWT", "value": { "detail": "The authentication token could not be validated. Please ensure your token is valid and try again.", "title": "Unauthorized", "type": "ANL_00401" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authentication failed — the JWT is missing, malformed, invalid, or expired (`ANL_00401`). Request a new token via `POST /oauth/token` before retrying." }, "403": { "content": { "application/problem+json": { "examples": { "forbidden": { "summary": "ANL_00403 — Instance scope not accessible with this token", "value": { "detail": "Access denied. The requested instance IDs are not accessible with this token.", "title": "Forbidden", "type": "ANL_00403" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "Authorization failed — the JWT is valid but the requested scope is not accessible with this token (`ANL_00403`). Typically one or more `instanceIds` are not bound to the client." }, "500": { "content": { "application/problem+json": { "examples": { "ANL_00500": { "summary": "ANL_00500 — Unexpected server error", "value": { "detail": "An unexpected error occurred while processing the request.", "title": "Internal Error", "type": "ANL_00500" } } }, "schema": { "$ref": "#/components/schemas/ProblemDetailDto" } } }, "description": "An unexpected error occurred while processing the request (`ANL_00500`). The request was not processed and the credentials are not implicated — retry with exponential backoff." } }, "security": [ { "JWT": [] } ], "summary": "Post performance metrics", "tags": [ "Post Level" ] } } }, "security": [ { "JWT": [] } ], "servers": [ { "url": "https://reporting.api.later.com" } ], "tags": [], "x-ext-urls": {} }