HighLevel: Get Social Media Statistics

← Social planner operations · Get started

Operation gohighlevel.get_statistics

Provider route: POST /social-media-posting/statistics. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/gohighlevel with npm, or alter-sdk-gohighlevel with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { HighLevelIntegration } from "@alter-ai/gohighlevel";

async function execute(input: Parameters<HighLevelIntegration["socialPlanner"]["getStatistics"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new HighLevelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.socialPlanner.getStatistics(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_gohighlevel import HighLevelIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = HighLevelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.social_planner.get_statistics(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Required within parent	Additional keys: not allowed
query.locationId	string	Required within parent
body	object	Required within parent
body.currentRange	object	Optional	Custom date range for the current analytics period. If omitted, defaults to the last 7 days (excluding today) with automatic comparison to the previous 7 days.
body.currentRange.endDate	string	Required within parent	End date in ISO 8601 format. Must be after startDate. Format: date-time
body.currentRange.startDate	string	Required within parent	Start date in ISO 8601 format. Format: date-time
body.platforms	array	Optional	Array of social media platforms to filter analytics by. If not provided, all platforms will be included. NOTE: Linkedin (PAGE only) and Tiktok (BUSINESS only) are supported.
body.platforms[]	string	Each item	One of: facebook, instagram, linkedin, google, pinterest, youtube, tiktok
body.prevRange	object	Optional	Comparison date range. Can only be provided when currentRange is also present. If omitted while currentRange is present, no comparison data is returned.
body.prevRange.endDate	string	Required within parent	End date in ISO 8601 format. Must be after startDate. Format: date-time
body.prevRange.startDate	string	Required within parent	Start date in ISO 8601 format. Format: date-time
body.profileIds	array	Required within parent	Array of connected social media account IDs to fetch analytics for. This can be found as ‘profileId’ in /accounts api. Maximum items: 100 Minimum items: 1
body.profileIds[]	string	Each item

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	object	Root
message	string	Optional	Success message indicating the analytics were built successfully
results	object	Optional	Analytics data grouped by metrics and platforms
results.breakdowns	object	Optional	Detailed breakdowns by metric and platform
results.breakdowns.engagement	object	Optional	Engagement metrics breakdown by platform Additional keys: see wildcard field
results.breakdowns.engagement.*	object	Additional keys
results.breakdowns.engagement.*.change	JSON	Optional
results.breakdowns.engagement.*.change (anyOf 1)	number	Alternative	Percentage change in engagement compared to previous period
results.breakdowns.engagement.*.change (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.engagement.*.comments	JSON	Optional
results.breakdowns.engagement.*.comments (anyOf 1)	number	Alternative	Number of comments received on this platform
results.breakdowns.engagement.*.comments (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.engagement.*.likes	JSON	Optional
results.breakdowns.engagement.*.likes (anyOf 1)	number	Alternative	Number of likes received on this platform
results.breakdowns.engagement.*.likes (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.engagement.*.shares	JSON	Optional
results.breakdowns.engagement.*.shares (anyOf 1)	number	Alternative	Number of shares on this platform
results.breakdowns.engagement.*.shares (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.impressions	object	Optional	Impressions breakdown by platform
results.breakdowns.impressions.platforms	object	Optional	Platform-specific impression counts with change percentages Additional keys: see wildcard field
results.breakdowns.impressions.platforms.*	object	Additional keys
results.breakdowns.impressions.platforms.*.change	JSON	Optional
results.breakdowns.impressions.platforms.*.change (anyOf 1)	number	Alternative	Percentage change compared to previous period
results.breakdowns.impressions.platforms.*.change (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.impressions.platforms.*.value	JSON	Optional
results.breakdowns.impressions.platforms.*.value (anyOf 1)	number	Alternative	Number of impressions for this platform
results.breakdowns.impressions.platforms.*.value (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.impressions.total	JSON	Optional
results.breakdowns.impressions.total (anyOf 1)	number	Alternative	Total impressions across all platforms
results.breakdowns.impressions.total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.impressions.totalChange	JSON	Optional
results.breakdowns.impressions.totalChange (anyOf 1)	number	Alternative	Percentage change in total impressions compared to previous period
results.breakdowns.impressions.totalChange (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.posts	object	Optional	Post count breakdown by platform
results.breakdowns.posts.platforms	object	Optional	Platform-specific post counts with change percentages Additional keys: see wildcard field
results.breakdowns.posts.platforms.*	object	Additional keys
results.breakdowns.posts.platforms.*.change	JSON	Optional
results.breakdowns.posts.platforms.*.change (anyOf 1)	number	Alternative	Percentage change compared to previous period
results.breakdowns.posts.platforms.*.change (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.posts.platforms.*.value	JSON	Optional
results.breakdowns.posts.platforms.*.value (anyOf 1)	number	Alternative	Number of posts for this platform
results.breakdowns.posts.platforms.*.value (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.posts.total	JSON	Optional
results.breakdowns.posts.total (anyOf 1)	number	Alternative	Total number of posts across all platforms
results.breakdowns.posts.total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.posts.totalChange	JSON	Optional
results.breakdowns.posts.totalChange (anyOf 1)	number	Alternative	Percentage change in total posts compared to previous period
results.breakdowns.posts.totalChange (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.reach	object	Optional	Reach breakdown by platform
results.breakdowns.reach.platforms	object	Optional	Platform-specific reach counts with change percentages Additional keys: see wildcard field
results.breakdowns.reach.platforms.*	object	Additional keys
results.breakdowns.reach.platforms.*.change	JSON	Optional
results.breakdowns.reach.platforms.*.change (anyOf 1)	number	Alternative	Percentage change compared to previous period
results.breakdowns.reach.platforms.*.change (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.reach.platforms.*.value	JSON	Optional
results.breakdowns.reach.platforms.*.value (anyOf 1)	number	Alternative	Reach count for this platform
results.breakdowns.reach.platforms.*.value (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.reach.total	JSON	Optional
results.breakdowns.reach.total (anyOf 1)	number	Alternative	Total reach across all platforms
results.breakdowns.reach.total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.breakdowns.reach.totalChange	JSON	Optional
results.breakdowns.reach.totalChange (anyOf 1)	number	Alternative	Percentage change in total reach compared to previous period
results.breakdowns.reach.totalChange (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.dayRange	array	Optional	Array of day names for the analytics period
results.dayRange[]	string	Each item
results.demographics	object	Optional	Demographic data breakdown
results.demographics.age	object	Optional	Age distribution of audience
results.demographics.age.totals	object	Optional	Total counts by age group
results.demographics.age.totals.13-17	JSON	Optional
results.demographics.age.totals.13-17 (anyOf 1)	number	Alternative	Number of audience members aged 13-17
results.demographics.age.totals.13-17 (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.demographics.age.totals.18-24	JSON	Optional
results.demographics.age.totals.18-24 (anyOf 1)	number	Alternative	Number of audience members aged 18-24
results.demographics.age.totals.18-24 (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.demographics.age.totals.25-34	JSON	Optional
results.demographics.age.totals.25-34 (anyOf 1)	number	Alternative	Number of audience members aged 25-34
results.demographics.age.totals.25-34 (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.demographics.age.totals.35-44	JSON	Optional
results.demographics.age.totals.35-44 (anyOf 1)	number	Alternative	Number of audience members aged 35-44
results.demographics.age.totals.35-44 (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.demographics.age.totals.45-54	JSON	Optional
results.demographics.age.totals.45-54 (anyOf 1)	number	Alternative	Number of audience members aged 45-54
results.demographics.age.totals.45-54 (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.demographics.age.totals.55-64	JSON	Optional
results.demographics.age.totals.55-64 (anyOf 1)	number	Alternative	Number of audience members aged 55-64
results.demographics.age.totals.55-64 (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.demographics.age.totals.65+	JSON	Optional
results.demographics.age.totals.65+ (anyOf 1)	number	Alternative	Number of audience members aged 65 and above
results.demographics.age.totals.65+ (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.demographics.gender	object	Optional	Gender distribution of audience
results.demographics.gender.totals	object	Optional	Total counts and percentages by gender
results.demographics.gender.totals.female	object	Optional	Female audience statistics
results.demographics.gender.totals.female.percentage	JSON	Optional
results.demographics.gender.totals.female.percentage (anyOf 1)	number	Alternative	Percentage of female audience
results.demographics.gender.totals.female.percentage (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.demographics.gender.totals.female.total	JSON	Optional
results.demographics.gender.totals.female.total (anyOf 1)	number	Alternative	Total number of female audience members
results.demographics.gender.totals.female.total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.demographics.gender.totals.male	object	Optional	Male audience statistics
results.demographics.gender.totals.male.percentage	JSON	Optional
results.demographics.gender.totals.male.percentage (anyOf 1)	number	Alternative	Percentage of male audience
results.demographics.gender.totals.male.percentage (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.demographics.gender.totals.male.total	JSON	Optional
results.demographics.gender.totals.male.total (anyOf 1)	number	Alternative	Total number of male audience members
results.demographics.gender.totals.male.total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.demographics.gender.totals.unknown	object	Optional	Unknown gender audience statistics
results.demographics.gender.totals.unknown.percentage	JSON	Optional
results.demographics.gender.totals.unknown.percentage (anyOf 1)	number	Alternative	Percentage of audience with unknown gender
results.demographics.gender.totals.unknown.percentage (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.demographics.gender.totals.unknown.total	JSON	Optional
results.demographics.gender.totals.unknown.total (anyOf 1)	number	Alternative	Total number of audience members with unknown gender
results.demographics.gender.totals.unknown.total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.platformTotals	object	Optional	Platform-wise totals with time series data
results.platformTotals.followers	object	Optional	Daily follower counts by platform Additional keys: see wildcard field
results.platformTotals.followers.*	object	Additional keys
results.platformTotals.followers.*.series	array	Optional	Daily follower counts over the analytics period
results.platformTotals.followers.*.series[]	JSON	Each item
results.platformTotals.followers.*.series[] (anyOf 1)	number	Alternative
results.platformTotals.followers.*.series[] (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.platformTotals.followers.*.total	JSON	Optional
results.platformTotals.followers.*.total (anyOf 1)	number	Alternative	Total followers for this platform
results.platformTotals.followers.*.total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.platformTotals.impressions	object	Optional	Daily impression counts by platform Additional keys: see wildcard field
results.platformTotals.impressions.*	object	Additional keys
results.platformTotals.impressions.*.series	array	Optional	Daily impression counts over the analytics period
results.platformTotals.impressions.*.series[]	JSON	Each item
results.platformTotals.impressions.*.series[] (anyOf 1)	number	Alternative
results.platformTotals.impressions.*.series[] (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.platformTotals.impressions.*.total	JSON	Optional
results.platformTotals.impressions.*.total (anyOf 1)	number	Alternative	Total impressions for this platform
results.platformTotals.impressions.*.total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.platformTotals.likes	object	Optional	Daily like counts by platform Additional keys: see wildcard field
results.platformTotals.likes.*	object	Additional keys
results.platformTotals.likes.*.series	array	Optional	Daily like counts over the analytics period
results.platformTotals.likes.*.series[]	JSON	Each item
results.platformTotals.likes.*.series[] (anyOf 1)	number	Alternative
results.platformTotals.likes.*.series[] (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.platformTotals.likes.*.total	JSON	Optional
results.platformTotals.likes.*.total (anyOf 1)	number	Alternative	Total likes for this platform
results.platformTotals.likes.*.total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.postPerformance	object	Optional	Post performance metrics over time
results.postPerformance.comments	array	Optional	Daily comments over the analytics period
results.postPerformance.comments[]	JSON	Each item
results.postPerformance.comments[] (anyOf 1)	number	Alternative
results.postPerformance.comments[] (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.postPerformance.impressions	array	Optional	Daily impressions over the analytics period
results.postPerformance.impressions[]	JSON	Each item
results.postPerformance.impressions[] (anyOf 1)	number	Alternative
results.postPerformance.impressions[] (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.postPerformance.likes	array	Optional	Daily likes over the analytics period
results.postPerformance.likes[]	JSON	Each item
results.postPerformance.likes[] (anyOf 1)	number	Alternative
results.postPerformance.likes[] (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.postPerformance.posts	object	Optional	Number of posts published per day, organized by platform
results.totals	object	Optional	Aggregated metrics totals
results.totals.comments	JSON	Optional
results.totals.comments (anyOf 1)	number	Alternative	Total number of comments received
results.totals.comments (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.totals.followers	JSON	Optional
results.totals.followers (anyOf 1)	number	Alternative	Total number of followers across all platforms
results.totals.followers (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.totals.impressions	JSON	Optional
results.totals.impressions (anyOf 1)	number	Alternative	Total number of impressions across all posts
results.totals.impressions (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.totals.likes	JSON	Optional
results.totals.likes (anyOf 1)	number	Alternative	Total number of likes received
results.totals.likes (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
results.totals.posts	JSON	Optional
results.totals.posts (anyOf 1)	number	Alternative	Total number of posts published
results.totals.posts (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
traceId	string	Optional	Unique identifier for tracking this request

Policy, approvals and errors

SDK function policy ID: gohighlevel.get_statistics. Catalog operation: get-statistics. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["socialplanner/statistics.readonly"]

Pinned headers: {"Version": "v3"}

Official provider source