Agorapulse Reports API
Pull audience, content and community-management insights.
OpenAPI Specification
openapi: 3.2.0
info:
title: Agorapulse Reports API
description: "# Agorapulse API\n\nWelcome to the Agorapulse API. Use it to manage publishing, social inbox conversations, analytics and your content library programmatically.\n\nThe API is organized around REST, uses resource-oriented URLs, returns JSON, and relies on standard HTTP response codes and verbs.\n\n## Base URL\n\nAll requests go to the base URL shown in the **Server** selector, and every endpoint is versioned under a `/v1.0/` prefix.\n\n## Authentication\n\nThe API authenticates requests with an **API key** sent in the `X-API-KEY` HTTP header. Every request must include it:\n\n```http\nGET /v1.0/core/organizations HTTP/1.1\nHost: api.agorapulse.com\nX-API-KEY: your-api-key\n```\n\n```bash\ncurl https://api.agorapulse.com/v1.0/core/organizations \\\n -H \"X-API-KEY: your-api-key\"\n```\n\nKeep your API key secret: it grants access to your account's data. Requests without a valid key return `401 Unauthorized`.\n\n## Resource hierarchy\n\nMost resources are nested under an organization and a workspace:\n\n```\n/v1.0/<domain>/organizations/{organizationId}/workspaces/{workspaceId}/...\n```\n\nStart from `GET /v1.0/core/organizations` to discover your organizations, then list their workspaces and profiles.\n\n## Errors\n\nThe API uses conventional HTTP status codes: `2xx` for success, `4xx` for client errors (a missing or invalid parameter, an unknown resource, a missing API key), and `5xx` for server errors.\n\nError responses carry a JSON body describing the problem, except for `405`, `406` and `415`, which answer with a status only:\n\n```json\n{\n \"code\": 1005,\n \"subCode\": 1104,\n \"message\": \"Media not found: pubmedia_abc123\"\n}\n```\n\n`code` identifies the error family: either a global one (`1` internal, `2` unauthorized, `3` rate limit exceeded, `4` unprocessable input, `5` validation failed), or the component that produced the error. That component is usually the feature you addressed, but not always — a request whose path matches no endpoint is rejected by the API gateway itself and carries the gateway's own code, `1013`, whichever feature the path pointed at. `subCode` is optional and, when present, pinpoints the exact cause within that component; the endpoints that return one document its values. `message` is a human-readable explanation and is not meant to be parsed.\n\n## Webhooks\n\nAgorapulse can push events to your endpoints. See the **Webhooks** section for the available events (for example `PUBLISHING_POST` and `INBOX_ITEM`) and their payloads.\n"
version: '1.0'
contact:
name: Agorapulse API Support
url: https://www.agorapulse.com
email: support@agorapulse.com
x-logo:
url: docs/img/logo.svg
altText: Agorapulse
servers:
- url: https://api.agorapulse.com
description: Production
security:
- bearerAuth: []
tags:
- name: Reports
description: Pull audience, content and community-management insights.
paths:
/v1.0/report/organizations/{organizationId}/workspaces/{workspaceId}/profiles/{profileUid}/insights/audience:
get:
tags:
- Reports
summary: Get audience report
description: Get audience report
operationId: getAudience
parameters:
- name: organizationId
in: path
description: Organization id
required: true
schema:
type: string
- name: workspaceId
in: path
description: Workspace id
required: true
schema:
type: string
- name: profileUid
in: path
description: Profile uid
required: true
schema:
type: string
- name: since
in: query
required: true
explode: false
schema:
type: string
- name: until
in: query
required: true
explode: false
schema:
type: string
responses:
'200':
description: Audience is returned
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAudienceInsight'
/v1.0/report/organizations/{organizationId}/workspaces/{workspaceId}/profiles/{profileUid}/insights/communitymanagement:
get:
tags:
- Reports
summary: Get community management report
description: Get community management report
operationId: getCommunityManagement
parameters:
- name: organizationId
in: path
description: Organization id
required: true
schema:
type: string
- name: workspaceId
in: path
description: Workspace id
required: true
schema:
type: string
- name: profileUid
in: path
description: Profile uid
required: true
schema:
type: string
- name: since
in: query
required: true
explode: false
schema:
type: string
- name: until
in: query
required: true
explode: false
schema:
type: string
responses:
'200':
description: Community management is returned
content:
application/json:
schema:
$ref: '#/components/schemas/CommunityManagementInsight'
/v1.0/report/organizations/{organizationId}/workspaces/{workspaceId}/profiles/{profileUid}/insights/content:
get:
tags:
- Reports
summary: Get content report
description: Get content report
operationId: getContentReport
parameters:
- name: organizationId
in: path
description: Organization id
required: true
schema:
type: string
- name: workspaceId
in: path
description: Workspace id
required: true
schema:
type: string
- name: profileUid
in: path
description: Profile uid
required: true
schema:
type: string
- name: since
in: query
required: true
explode: false
schema:
type: string
- name: until
in: query
required: true
explode: false
schema:
type: string
responses:
'200':
description: Content report is returned
content:
application/json:
schema:
$ref: '#/components/schemas/ContentReportInsight_1'
components:
schemas:
YoutubeCommunityManagementAction:
type: object
allOf:
- $ref: '#/components/schemas/CommunityManagementAction'
- type: object
properties:
removedCount:
type: integer
description: Number of items removed
format: int64
example: 5
TiktokAudienceInsight:
type: object
properties:
followersCount:
type: integer
description: Number of total followers
format: int64
example: 199
followersGainedCount:
type: integer
description: Number of followers gained (only available for Tiktok business)
format: int64
example: 9
followersLostCount:
type: integer
description: Number of followers lost (only available for Tiktok business)
format: int64
example: 2
followersNetGrowth:
type: integer
description: Net follower growth (gained minus lost)
format: int64
example: 7
engagementRatePerView:
type: number
description: Ratio of engagement to view as a percentage
format: double
example: 24.2
viewsCount:
type: integer
description: Number of views
format: int64
example: 90
likesCount:
type: integer
description: Number of likes
format: int64
example: 12
publishedVideoCount:
type: integer
description: Number of published videos
format: int64
example: 1
receivedCommentsCount:
type: integer
description: Number of received comments
format: int64
example: 6
sharesCount:
type: integer
description: Number of shares
format: int64
example: 23
description: Tiktok Specific Audience Insights
allOf:
- $ref: '#/components/schemas/AudienceReportByDate'
YoutubeContentReportInsight:
type: object
properties:
addedToPlaylistCount:
type: integer
description: Number of times this video was added to a playlist
format: int64
example: 830
commentsCount:
type: integer
description: Number of comments
format: int64
example: 2
dislikeCount:
type: integer
description: Number of dislikes
format: int64
example: 15
subscribersGainCount:
type: integer
description: Number of subscribers gained from the video
format: int64
example: 10
subscribersLostCount:
type: integer
description: Number of subscribers lost from the video
format: int64
example: 2
likesCount:
type: integer
description: Number of likes
format: int64
example: 65
removedFromPlaylistCount:
type: integer
description: Number of times this video was removed to a playlist
format: int64
example: 400
sharesCount:
type: integer
description: Number of shares
format: int64
example: 46
videoViewsCount:
type: integer
description: Number of video views
format: int64
example: 23
videoViewsTimeWatchedRate:
type: number
description: Ratio of average viewing time to total video duration as a percentage
format: double
example: 75.8
description: Youtube Specific Content Report Insights
allOf:
- $ref: '#/components/schemas/ContentReportData'
CommunityManagementAction:
type: object
properties:
averageResponseTime:
type: integer
description: Average time to respond
format: int64
example: 15
repliesCount:
type: integer
description: Number of replies
format: int64
example: 2
reviewsCount:
type: integer
description: Number of reviews
format: int64
example: 10
username:
type: string
description: Name of the user who performed community management actions
example: User123
FacebookCommunityManagementAction:
type: object
allOf:
- $ref: '#/components/schemas/CommunityManagementAction'
- type: object
properties:
removedCount:
type: integer
description: Number of items removed
format: int64
example: 5
CommunityManagementInsight:
required:
- data
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CommunityManagementByDate'
description: List of community management insight
ContentReportInsight_1:
required:
- data
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ContentReportData'
description: List of content report insight
TwitterAudienceInsight:
type: object
properties:
followersCount:
type: integer
description: Number of total followers
format: int64
example: 199
followersGainedCount:
type: integer
description: Number of followers gained
format: int64
example: 9
deprecated: true
followersNetGrowth:
type: integer
description: Net follower growth (gained minus lost)
format: int64
example: 9
engagementRatePerImpression:
type: number
description: Ratio of engagement to impression as a percentage
format: double
example: 24.2
impressionsCount:
type: integer
description: Number of impressions
format: int64
example: 245
likesCount:
type: integer
description: Number of likes
format: int64
example: 65
mentionsCount:
type: integer
description: Number of mentions
format: int64
example: 12
quotePostsCount:
type: integer
description: Number of reposts
format: int64
example: 9
publishedLinksCount:
type: integer
description: Number of published links
format: int64
example: 3
publishedMediaCount:
type: integer
description: Number of published media
format: int64
example: 23
publishedTextCount:
type: integer
description: Number of published text
format: int64
example: 1
receivedMessagesCount:
type: integer
description: Number of received messages
format: int64
example: 3
receivedCommentsCount:
type: integer
description: Number of received comments
format: int64
example: 6
deprecated: true
repliesCount:
type: integer
description: Number of replies
format: int64
example: 6
sharesCount:
type: integer
description: Number of shares
format: int64
example: 23
positiveItemsCount:
type: integer
description: Number of items with positive sentiment
format: int64
example: 24
neutralItemsCount:
type: integer
description: Number of items with neutral sentiment
format: int64
example: 2
negativeItemsCount:
type: integer
description: Number of items with negative sentiment
format: int64
example: 12
sentimentScore:
type: number
description: Ratio of positive items divided by the total of positive and negative items
format: double
example: 50
description: Twitter Specific Audience Insights
allOf:
- $ref: '#/components/schemas/AudienceReportByDate'
AudienceReportByDate:
type: object
properties:
date:
type: string
description: Date in ISO format YYYY-MM-DD
example: '2020-04-18T00:00:00.000Z'
engagementCount:
type: integer
description: Number of engagement
format: int64
example: 99
description: Common properties for audience report insight
oneOf:
- $ref: '#/components/schemas/FacebookAudienceInsight'
- $ref: '#/components/schemas/TwitterAudienceInsight'
- $ref: '#/components/schemas/LinkedinAudienceInsight'
- $ref: '#/components/schemas/InstagramAudienceInsight'
- $ref: '#/components/schemas/TiktokAudienceInsight'
- $ref: '#/components/schemas/YoutubeAudienceInsight'
- $ref: '#/components/schemas/ThreadsAudienceInsight'
InstagramCommunityManagementAction:
type: object
allOf:
- $ref: '#/components/schemas/CommunityManagementAction'
- type: object
properties:
removedCount:
type: integer
description: Number of items removed
format: int64
example: 5
LinkedinAudienceInsight:
type: object
properties:
clicksCount:
type: integer
description: Number of clicks on posts
format: int64
example: 2
organicClicksCount:
type: integer
description: Number of organic clicks on posts
format: int64
example: 0
paidClicksCount:
type: integer
description: Number of paid clicks on posts
format: int64
example: 2
receivedCommentsCount:
type: integer
description: Number of received comments
format: int64
example: 6
organicReceivedCommentsCount:
type: integer
description: Number of organic comments received on posts
format: int64
example: 1
paidReceivedCommentsCount:
type: integer
description: Number of paid comments received on posts
format: int64
example: 5
organicEngagementCount:
type: integer
description: Number of organic engagement
format: int64
example: 33
paidEngagementCount:
type: integer
description: Number of paid engagement
format: int64
example: 66
engagementRatePerImpression:
type: number
description: Ratio of engagement to impression as a percentage
format: double
example: 24.2
organicEngagementRatePerImpression:
type: number
description: Ratio of organic engagement to impression as a percentage
format: double
example: 10.2
paidEngagementRatePerImpression:
type: number
description: Ratio of paid engagement to impression as a percentage
format: double
example: 14
engagementRatePerReach:
type: number
description: Ratio of engagement to reach as a percentage
format: double
example: 34.8
organicEngagementRatePerReach:
type: number
description: Ratio of organic engagement to reach as a percentage
format: double
example: 14.4
paidEngagementRatePerReach:
type: number
description: Ratio of paid engagement to reach as a percentage
format: double
example: 20.4
followersCount:
type: integer
description: Number of total followers
format: int64
example: 199
followersGainedCount:
type: integer
description: Number of followers gained
format: int64
example: 9
deprecated: true
followersNetGrowth:
type: integer
description: Net follower growth (gained minus lost)
format: int64
example: 9
impressionsCount:
type: integer
description: Number of impressions
format: int64
example: 245
organicImpressionsCount:
type: integer
description: Number of organic impressions
format: int64
example: 90
paidImpressionsCount:
type: integer
description: Number of paid impressions
format: int64
example: 155
likesCount:
type: integer
description: Number of likes
format: int64
example: 449
organicLikesCount:
type: integer
description: Number of organic likes on posts
format: int64
example: 58
paidLikesCount:
type: integer
description: Number of paid likes on posts
format: int64
example: 391
organicFollowersGainedCount:
type: integer
description: Number of organic followers gained
format: int64
example: 24
deprecated: true
paidFollowersGainedCount:
type: integer
description: Number of paid followers gained
format: int64
example: 54
deprecated: true
organicFollowersNetGrowth:
type: integer
description: Net organic follower growth (gained minus lost)
format: int64
example: 24
paidFollowersNetGrowth:
type: integer
description: Net paid follower growth (gained minus lost)
format: int64
example: 54
publishedPostsCount:
type: integer
description: Number of posts published
format: int64
example: 9
reachCount:
type: integer
description: Number of reach
format: int64
example: 192
organicReachCount:
type: integer
description: Number of organic reach
format: int64
example: 43
paidReachCount:
type: integer
description: Number of paid reach
format: int64
example: 149
removedCount:
type: integer
description: Number of removed items
format: int64
example: 1
positiveItemsCount:
type: integer
description: Number of items with positive sentiment
format: int64
example: 24
neutralItemsCount:
type: integer
description: Number of items with neutral sentiment
format: int64
example: 2
negativeItemsCount:
type: integer
description: Number of items with negative sentiment
format: int64
example: 12
sentimentScore:
type: number
description: Ratio of positive items divided by the total of positive and negative items
format: double
example: 50
sharesCount:
type: integer
description: Number of shares
format: int64
example: 23
organicSharesCount:
type: integer
description: Number of organic shares
format: int64
example: 3
paidSharesCount:
type: integer
description: Number of paid shares
format: int64
example: 20
description: Linkedin Specific Audience Insights
allOf:
- $ref: '#/components/schemas/AudienceReportByDate'
LinkedinCommunityManagementAction:
type: object
allOf:
- $ref: '#/components/schemas/CommunityManagementAction'
- type: object
properties:
removedCount:
type: integer
description: Number of items removed
format: int64
example: 5
TikTokContentReportInsight:
type: object
properties:
completionRate:
type: integer
description: Average viewing time relative to total video duration
format: int64
example: null
commentCount:
type: integer
description: Number of comments
format: int64
example: 583
engagementRatePerView:
type: number
description: Ratio of engagement to view as a percentage
format: double
example: 78.3
engagementRatePerReach:
type: number
description: Ratio of engagement to reach as a percentage
format: double
example: 67.5
viewsCount:
type: integer
description: Number of views
format: int64
example: 928
likeCount:
type: integer
description: Number of likes
format: int64
example: 583
reachCount:
type: integer
description: Number of reach
format: int64
example: 583
shareCount:
type: integer
description: Number of shares
format: int64
example: 583
videoCompletedCount:
type: integer
description: Number of times the video is watched fully
format: int64
example: 76
videoReplaysCount:
type: integer
description: Number of video replays
format: int64
example: 45
videoViewsTimeWatchedCount:
type: integer
description: Total viewing time in seconds
format: int64
example: 12
videoViewersRateByGender:
type: object
additionalProperties:
type: number
format: double
description: Video viewers rate by gender
example:
Female: 0.457
Male: 0.403
Other: 0.14
videoViewersRateByCountry:
type: object
additionalProperties:
type: number
format: double
description: Video viewers rate by country
example:
CA: 0.0132
GB: 0.7303
US: 0.2565
videoViewersRateByCity:
type: object
additionalProperties:
type: number
format: double
description: Video viewers rate by city
example:
US Cincinnati: 0.597
US Los Angeles: 0.403
description: TikTok Specific Content Report Insights
allOf:
- $ref: '#/components/schemas/ContentReportData'
OpenAudienceInsight:
required:
- data
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AudienceReportByDate'
description: List of social network audience insight
LinkedinContentReportInsight:
type: object
properties:
clicksCount:
type: integer
description: Number of clicks
format: int64
example: 573
organicClicksCount:
type: integer
description: Number of organic clicks
format: int64
example: 173
paidClicksCount:
type: integer
description: Number of paid clicks
format: int64
example: 400
commentsCount:
type: integer
description: Number of comments
format: int64
example: 23
organicCommentsCount:
type: integer
description: Number of organic comments
format: int64
example: 5
paidCommentsCount:
type: integer
description: Number of paid comments
format: int64
example: 18
organicEngagementCount:
type: integer
description: Number of organic engagement
format: int64
example: 220
paidEngagementCount:
type: integer
description: Number of paid engagement
format: int64
example: 557
engagementRatePerImpression:
type: number
description: Ratio of engagement to impression as a percentage
format: double
example: 68.8
organicEngagementRatePerImpression:
type: number
description: Ratio of organic engagement to impression as a percentage
format: double
example: 21.2
paidEngagementRatePerImpression:
type: number
description: Ratio of paid engagement to impression as a percentage
format: double
example: 47.6
engagementRatePerReach:
type: number
description: Ratio of engagement to reach as a percentage
format: double
example: 65.2
organicEngagementRatePerReach:
type: number
description: Ratio of organic engagement to reach as a percentage
format: double
example: 17.5
paidEngagementRatePerReach:
type: number
description: Ratio of paid engagement to reach as a percentage
format: double
example: 47.7
impressionsCount:
type: integer
description: Number of impressions
format: int64
example: 756
organicImpressionsCount:
type: integer
description: Number of organic impressions
format: int64
example: 276
paidImpressionsCount:
type: integer
description: Number of paid impressions
format: int64
example: 480
likesCount:
type: integer
description: Number of likes
format: int64
example: 215
organicLikesCount:
type: integer
description: Number of organic likes
format: int64
example: 69
paidLikesCount:
type: integer
description: Number of paid likes
format: int64
example: 146
reachCount:
type: integer
description: Number of reach
format: int64
example: 1200
organicReachCount:
type: integer
description: Number of organic reach
format: int64
example: 350
paidReachCount:
type: integer
description: Number of paid reach
format: int64
example: 850
sharesCount:
type: integer
description: Number of shares
format: int64
example: 21
organicSharesCount:
type: integer
description: Number of organic shares
format: int64
example: 3
paidSharesCount:
type: integer
description: Number of paid shares
format: int64
example: 18
videoViewsCount:
type: integer
description: Number of video views
format: int64
example: 86
videoViewsTimeWatchedCount:
type: integer
description: The time the video was watched in milliseconds
format: int64
example: 86
videoViewersCount:
type: integer
description: Number of viewers who made engaged plays on the video
format: int64
example: 86
video3sViewsTimeWatchedCount:
type: integer
description: The time watched in milliseconds for video play-pause cycles that are at least 3 seconds
format: int64
example: 86
organicVideoViewsCount:
type: integer
description: Number of organic video views
format: int64
example: 14
paidVideoViewsCount:
type: integer
description: Number of paid video views
format: int64
example: 72
description: Linkedin Specific Content Report Insights
allOf:
- $ref: '#/components/schemas/ContentReportData'
InstagramContentReportInsight:
type: object
properties:
avgWatchTime:
type: integer
description: Average viewing time
format: int64
example: 12
organicAvgWatchTime:
type: integer
description: Average organic viewing time
format: int64
example: 12
paidAvgWatchTime:
type: integer
description: Average paid viewing time
format: int64
example: 12
commentsCount:
type: integer
description: Number of comments
format: int64
example: 2
organicCommentsCount:
type: integer
description: Number of organic comments
format: int64
example: 2
paidCommentsCount:
type: integer
description: Number of paid comments
format: int64
example: 2
engagementCount:
type: integer
description: Number of engagement
format: int64
example: 99
organicEngagementCount:
type: integer
description: Number of organic engagement
format: int64
example: 23
paidEngagementCount:
type: integer
description: Number of paid engagement
format: int64
example: 76
engagementRatePerImpression:
type: number
description: Ratio of engagement to impression as a percentage
format: double
example: 50
engagementRatePerReach:
type: number
description: Ratio of engagement to reach as a percentage
format: double
example: 50
organicEngagementRatePerImpression:
type: number
description: Ratio of organic engagement to organic impress
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/agorapulse/refs/heads/main/openapi/agorapulse-reports-api-openapi.yml