openapi: 3.1.1
info:
title: Publer Analytics API
description: 'The Publer API (v1) is a RESTful JSON interface for automating social media workflows
- scheduling, publishing, media management and analytics - across Facebook, Instagram, X/Twitter,
LinkedIn, TikTok, YouTube, Pinterest, Threads, Bluesky, Mastodon, Google Business Profiles, WordPress
and Telegram. Authentication is an API key sent as `Authorization: Bearer-API YOUR_API_KEY` together
with a `Publer-Workspace-Id` header. The API is available exclusively to Publer Business users.'
termsOfService: https://publer.com/terms
contact:
name: Publer Support
email: support@publer.com
url: https://publer.com/docs
version: 1.0.0
servers:
- url: https://app.publer.com/api/v1
security:
- BearerApiAuth: []
tags:
- name: Analytics
description: Endpoints for retrieving analytics data and charts
paths:
/analytics/{account_id}/best_times:
get:
summary: Get Best Times to Post for Account
description: Retrieves the optimal posting times for a specific social media account based on historical
analytics data. Returns a heatmap of posting performance across days of the week and hours of
the day, tailored to the specified account's audience engagement patterns.
tags:
- Analytics
parameters:
- schema:
type: string
name: Publer-Workspace-Id
in: header
description: ID of the workspace to retrieve best times from
required: true
- schema:
type: string
name: account_id
in: path
description: Social media account ID to analyze posting times for. When provided, analysis is
specific to this account's performance data
required: false
- schema:
type: string
enum:
- 'true'
- 'false'
name: competitors
in: query
description: Include competitor data in best times analysis. Set to 'true' to analyze competitor
posting patterns
required: false
- schema:
type: string
name: competitor_id
in: query
description: Specific competitor ID to analyze. Used in conjunction with competitors=true parameter
required: false
- schema:
type: string
format: date
name: from
in: query
description: Start date for analytics data range (YYYY-MM-DD format). Filters data from this date
onwards
required: true
- schema:
type: string
format: date
name: to
in: query
description: End date for analytics data range (YYYY-MM-DD format). Filters data up to this date
required: true
responses:
'200':
description: Best times to post data organized by day of the week and hour for the specific
account
content:
application/json:
schema:
type: object
description: Heatmap data showing optimal posting times with scores for each hour of each
day, specific to the account's audience
additionalProperties:
type: array
description: Array of 24 hourly scores (0-23) for each day of the week
items:
type: number
description: Engagement score for this hour (higher = better posting time)
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/401ErrorResponse'
'403':
description: Permission denied - requires analytics access or paying subscription
content:
application/json:
schema:
$ref: '#/components/schemas/403ErrorResponse'
operationId: getBestTimesToPostForAccount
/analytics/charts:
get:
summary: Get Available Analytics Charts
description: Retrieves a list of available analytics charts filtered by account type and chart type.
Charts include growth metrics (followers, connections), insights (engagement, reach), and demographics
(countries, ages).
tags:
- Analytics
parameters:
- schema:
type: string
name: Publer-Workspace-Id
in: header
description: ID of the workspace to retrieve charts from
required: true
- schema:
type: string
enum:
- ig_business
- fb_page
- twitter
- linkedin
- youtube
- tiktok
- google
- pin_business
- pin_personal
- threads
- wordpress_oauth
- in_profile
- in_page
- mastodon
- bluesky
name: account_type
in: query
description: Social media platform type to filter charts for (e.g., 'ig_business', 'fb_page',
'twitter', 'linkedin', 'youtube', 'tiktok', 'google', 'pin_business')
required: false
responses:
'200':
description: List of available charts with metadata
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: Unique identifier for the chart
title:
type: string
description: Display title of the chart
group_id:
type: string
description: Group category (growth, insights, demographics)
tooltip:
type: string
description: Tooltip text explaining the chart
type:
type: string
description: Chart visualization type
enum:
- vertical
- horizontal
- side_by_side
last_value:
type: boolean
description: Whether to show the most recent value
show_percentage:
type: boolean
description: Whether values should be displayed as percentages
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/401ErrorResponse'
'403':
description: Permission denied or missing required scope
content:
application/json:
schema:
$ref: '#/components/schemas/403ErrorResponse'
operationId: getAvailableAnalyticsCharts
/analytics/chart_data:
get:
summary: Get Analytics Chart Data
description: Retrieves analytics data for specific charts by their IDs. Returns current and previous
period data for comparison. Supports growth metrics, post insights, and demographic data.
tags:
- Analytics
parameters:
- schema:
type: string
name: Publer-Workspace-Id
in: header
description: ID of the workspace to retrieve data from
required: true
- schema:
type: array
items:
type: string
style: form
explode: true
name: chart_ids
in: query
description: Array of chart IDs to retrieve data for. Use chart IDs from the /analytics/charts
endpoint
required: true
- schema:
type: string
name: account_id
in: path
description: Optional account ID to filter analytics data for a specific social media account
required: false
- schema:
type: string
format: date
name: from
in: query
description: Start date for analytics data (YYYY-MM-DD format)
required: false
- schema:
type: string
format: date
name: to
in: query
description: End date for analytics data (YYYY-MM-DD format)
required: false
responses:
'200':
description: Analytics chart data with current and previous period values
content:
application/json:
schema:
type: object
properties:
current:
type: object
description: Current period data for requested charts
additionalProperties:
type: object
description: Chart-specific data structure with metrics and values
previous:
type: object
description: Previous period data for comparison
additionalProperties:
type: object
description: Previous period chart data for trend analysis
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/401ErrorResponse'
'403':
description: Permission denied or missing required scope
content:
application/json:
schema:
$ref: '#/components/schemas/403ErrorResponse'
operationId: getAnalyticsChartData
/analytics/{account_id}/hashtag_insights:
get:
summary: Get Hashtag Insights
description: Retrieves comprehensive analytics data for hashtags used in published posts. Provides
metrics like reach, engagement, likes, comments, shares, and video views for each hashtag, along
with recent posts using each hashtag and hashtag performance scores.
tags:
- Analytics
parameters:
- schema:
type: string
name: Publer-Workspace-Id
in: header
description: ID of the workspace to retrieve insights from
required: true
- schema:
type: string
format: date
name: from
in: query
description: Start date for hashtag insights data range (YYYY-MM-DD format). Filters posts scheduled
on or after this date
required: false
- schema:
type: string
format: date
name: to
in: query
description: End date for hashtag insights data range (YYYY-MM-DD format). Filters posts scheduled
on or before this date
required: false
- schema:
type: string
enum:
- posts
- reach
- likes
- comments
- shares
- video_views
name: sort_by
in: query
description: Field to sort hashtag results by. Supports various engagement and performance metrics
required: false
- schema:
type: string
enum:
- ASC
- DESC
name: sort_type
in: query
description: Sort order direction
required: false
- schema:
type: string
name: account_id
in: path
description: Filter hashtags for a specific social media account ID. If omitted, includes all
workspace accounts
required: false
- schema:
type: integer
minimum: 0
name: page
in: query
description: Page number for pagination (0-based indexing). Each page contains 10 hashtags
required: false
- schema:
type: string
name: query
in: query
description: Search query to filter hashtags by name using case-insensitive matching
required: false
- schema:
type: string
name: member_id
in: query
description: Filter hashtags by specific workspace member ID
required: false
responses:
'200':
description: Hashtag insights data with analytics metrics and pagination information
content:
application/json:
schema:
type: object
properties:
records:
type: array
description: Array of hashtags with detailed analytics data
items:
type: object
properties:
hashtag:
type: string
description: 'The hashtag text (without # symbol)'
posts:
type: integer
description: Number of posts using this hashtag
recent_posts:
type: array
description: Array of recent post objects using this hashtag (up to 3 posts)
items:
type: object
properties:
id:
type: string
description: Unique identifier for the post
text:
type: string
description: Post content text
scheduled_at:
type: string
format: date-time
description: Date and time when post was scheduled/published
reach:
type: integer
description: Total reach across all posts using this hashtag
likes:
type: integer
description: Total likes across all posts using this hashtag
comments:
type: integer
description: Total comments across all posts using this hashtag
shares:
type: integer
description: Total shares across all posts using this hashtag
engagement:
type: integer
description: Total engagement (likes + comments + shares) across all posts using
this hashtag
video_views:
type: integer
description: Total video views across all video posts using this hashtag
link_clicks:
type: integer
description: Total link clicks across all posts using this hashtag
post_clicks:
type: integer
description: Total post clicks across all posts using this hashtag
saves:
type: integer
description: Total saves across all posts using this hashtag
hashtag_score:
type: number
format: float
description: Performance score of the hashtag as percentage relative to overall
post engagement
total:
type: integer
description: Total number of hashtags matching the filter criteria (for pagination)
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/401ErrorResponse'
'403':
description: Permission denied - requires analytics access or paying subscription
content:
application/json:
schema:
$ref: '#/components/schemas/403ErrorResponse'
operationId: getHashtagInsights
/analytics/{account_id}/hashtag_performing_posts:
get:
summary: Get Hashtag Performing Posts
description: Retrieves the top performing posts for a specific hashtag. Returns up to 6 posts that
used the hashtag, with comprehensive analytics metrics including engagement, reach, likes, comments,
shares, and video views.
tags:
- Analytics
parameters:
- schema:
type: string
name: Publer-Workspace-Id
in: header
description: ID of the workspace to retrieve posts from
required: true
- schema:
type: string
name: hashtag
in: query
description: 'The hashtag to retrieve performing posts for (with # symbol). This parameter is
required to filter posts by the specific hashtag'
required: true
- schema:
type: string
format: date
name: from
in: query
description: Start date for posts data range (YYYY-MM-DD format). Filters posts scheduled on or
after this date
required: false
- schema:
type: string
format: date
name: to
in: query
description: End date for posts data range (YYYY-MM-DD format). Filters posts scheduled on or
before this date
required: false
- schema:
type: string
enum:
- scheduled_at
- reach
- engagement
- engagement_rate
- click_through_rate
- reach_rate
- postType
- likes
- video_views
- comments
- shares
- saves
- link_clicks
- post_clicks
name: sort_by
in: query
description: Field to sort post results by. Supports various engagement and performance metrics
required: false
- schema:
type: string
enum:
- ASC
- DESC
name: sort_type
in: query
description: Sort order direction
required: false
- schema:
type: string
name: account_id
in: path
description: Filter posts for a specific social media account ID. If omitted, includes all workspace
accounts
required: false
- schema:
type: string
name: member_id
in: query
description: Filter posts by specific workspace member ID
required: false
- schema:
type: string
name: query
in: query
description: Search query to filter posts by content text, title, or link information using case-insensitive
matching
required: false
responses:
'200':
description: Hashtag performing posts data with analytics metrics
content:
application/json:
schema:
type: array
description: Array of top performing posts using the specified hashtag (up to 6 posts)
items:
type: object
properties:
id:
type: string
description: Unique identifier for the post
text:
type: string
description: Post content text
title:
type: string
description: Post title if available
scheduled_at:
type: string
format: date-time
description: Date and time when post was scheduled/published
account_id:
type: string
description: ID of the social media account that published this post
hashtags:
type: array
description: Array of hashtags used in this post
items:
type: string
analytics:
type: object
description: Comprehensive analytics data for the post
properties:
reach:
type: integer
description: Total reach of the post
likes:
type: integer
description: Number of likes received
comments:
type: integer
description: Number of comments received
shares:
type: integer
description: Number of shares/reposts
engagement:
type: integer
description: Total engagement (likes + comments + shares)
engagement_rate:
type: number
format: float
description: Engagement rate as percentage
video_views:
type: integer
description: Number of video views (for video posts)
link_clicks:
type: integer
description: Number of link clicks
post_clicks:
type: integer
description: Number of post clicks
saves:
type: integer
description: Number of saves/bookmarks
details:
type: object
description: Additional post details and metadata
properties:
labels:
type: array
description: Labels assigned to this post
items:
type: object
properties:
id:
type: string
description: Label ID
name:
type: string
description: Label name
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/401ErrorResponse'
'403':
description: Permission denied - requires analytics access or paying subscription
content:
application/json:
schema:
$ref: '#/components/schemas/403ErrorResponse'
operationId: getHashtagPerformingPosts
/analytics/members:
get:
summary: Get Analytics Members Data
description: Retrieves analytics data for workspace members showing their posting activity and engagement
metrics.
tags:
- Analytics
parameters:
- schema:
type: string
name: Publer-Workspace-Id
in: header
description: ID of the workspace to retrieve members from
required: true
- schema:
type: string
format: date
name: from
in: query
description: Start date for analytics data range (YYYY-MM-DD format). Filters data from this date
onwards
required: true
- schema:
type: string
format: date
name: to
in: query
description: End date for analytics data range (YYYY-MM-DD format). Filters data up to this date
required: true
- schema:
type: string
name: account_id
in: query
description: Optional account ID to filter analytics data for a specific social media account
required: false
responses:
'200':
description: Members analytics data with performance metrics
content:
application/json:
schema:
type: array
description: List of members with their analytics data
items:
type: object
properties:
engagements:
type: integer
description: Total engagements (likes + comments + shares + post clicks) for the
member
posts:
type: integer
description: Total number of posts created by the member
reach:
type: integer
description: Total reach for the member's posts (only included for supported account
types)
account_ids:
type: array
description: List of account IDs the member posted to
items:
type: string
user:
type: object
description: User information for the member
properties:
id:
type: string
description: User ID
name:
type: string
description: User's display name
picture:
type: string
description: URL to user's profile picture
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/401ErrorResponse'
'403':
description: Permission denied - requires analytics access or paying subscription
content:
application/json:
schema:
$ref: '#/components/schemas/403ErrorResponse'
operationId: getAnalyticsMembersData
/analytics/{account_id}/post_insights:
get:
summary: Get Post Insights
description: Retrieves comprehensive analytics data for published posts with advanced filtering,
sorting, and pagination capabilities.
tags:
- Analytics
parameters:
- schema:
type: string
name: Publer-Workspace-Id
in: header
description: ID of the workspace to retrieve insights from
required: true
- schema:
type: string
enum:
- 'true'
- 'false'
name: competitors
in: query
description: Include competitor analysis data. Set to 'true' to retrieve competitor post insights
required: false
- schema:
type: string
name: account_id
in: path
description: Filter posts for a specific social media account ID. If omitted, includes all workspace
accounts. Used with competitors parameter for competitor-specific analysis
required: false
- schema:
type: string
name: competitor_id
in: query
description: Specific competitor account ID to analyze when competitors=true. Works in conjunction
with account_id parameter
required: false
- schema:
type: string
format: date
name: from
in: query
description: Start date for post insights data range (YYYY-MM-DD format). Filters posts scheduled
on or after this date
required: true
- schema:
type: string
format: date
name: to
in: query
description: End date for post insights data range (YYYY-MM-DD format). Filters posts scheduled
on or before this date
required: true
- schema:
type: string
name: query
in: query
description: Search query to filter posts by text content, title, link description, or video title
using case-insensitive matching
required: false
- schema:
type: string
enum:
- poll
- status
- link
- carousel
- photo
- git
- video
- reel
- document
- short
- article
- story
name: postType
in: query
description: Filter posts by specific post type (e.g., image, video, link, text, carousel)
required: false
- schema:
type: string
enum:
- scheduled_at
- reach
- engagement
- engagement_rate
- click_through_rate
- reach_rate
- postType
- likes
- video_views
- comments
- shares
- saves
- link_clicks
- post_clicks
name: sort_by
in: query
description: Field to sort results by. Supports various engagement and performance metrics
required: false
- schema:
type: string
enum:
- ASC
- DESC
name: sort_type
in: query
description: Sort order direction
required: false
- schema:
type: integer
minimum: 0
name: page
in: query
description: Page number for pagination (0-based indexing). Each page contains 10 posts
required: false
- schema:
type: string
name: member_id
in: query
description: Filter posts by specific workspace member/user ID who created or manages the posts
required: false
responses:
'200':
description: Post insights data with analytics metrics and pagination information
content:
application/json:
schema:
type: object
properties:
posts:
type: array
description: Array of posts with detailed analytics data
items:
type: object
properties:
id:
type: string
description: Unique identifier for the post
text:
type: string
description: Post content text
title:
type: string
description: Post title
scheduled_at:
type: string
format: date-time
description: Date and time when post was scheduled/published
post_type:
type: string
description: Type of post (image, video, link, etc.)
account_id:
type: string
description: ID of the social media account
details:
type: object
properties:
labels:
type: array
description: Labels/tags associated with the post
items:
type: object
properties:
id:
type: string
name:
type: string
color:
type: string
analytics:
type: object
description: Comprehensive analytics data for the post
properties:
reach:
type: integer
description: Number of unique users who saw the post
engagement:
type: integer
description: Total engagement count (likes + comments + shares + saves +
clicks)
engagement_rate:
type: number
format: float
description: Engagement rate as percentage
likes:
type: integ
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/publer/refs/heads/main/openapi/publer-analytics-api-openapi.yml