Agorapulse Reports API

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:
    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 impression as a percentage
          format: double
          example: 50
        organicEngagementRatePerReach:
          type: number
          description: Ratio of organic engagement to organic reach as a percentage
          format: double
          example: 50
        paidEngagementRatePerImpression:
          type: number
          description: Ratio of paid engagement to paid impression as a percentage
          format: double
          example: 50
        paidEngagementRatePerReach:
          type: number
          description: Ratio of paid engagement to paid reach as a percentage
          format: double
          example: 50
        impressionsCount:
          type: integer
          description: Number of impressions
          format: int64
          example: 245
        organicImpressionsCount:
          type: integer
          description: Number of organic impressions
          format: int64
          example: 245
        paidImpressionsCount:
          type: integer
          description: Number of paid impressions
          format: int64
          example: 245
        reachCount:
          type: integer
          description: Number of reach
          format: int64
          example: 1264
        organicReachCount:
          type: integer
          description: Number of organic reach
          format: int64
          example: 345
        paidReachCount:
          type: integer
          description: Number of paid reach
          format: int64
          example: 291
        likesCount:
          type: integer
          description: Number of likes
          format: int64
          example: 854
        organicLikesCount:
          type: integer
          description: Number of organic likes
          format: int64
          example: 854
        paidLikesCount:
          type: integer
          description: Number of paid likes
          format: int64
          example: 854
        repostsCount:
          type: integer
          description: Number of reposts
          format: int64
          example: 234
        savesCount:
          type: integer
          description: Number of saves
          format: int64
          example: 234
        organicSavesCount:
          type: integer
          description: Number of organic saves
          format: int64
          example: 234
        paidSavesCount:
          type: integer
          description: Number of paid saves
          format: int64
          example: 234
        sharesCount:
          type: integer
          description: Number of shares
          format: int64
          example: 46
        organicSharesCount:
          type: integer
          description: Number of organic shares
          format: int64
          example: 46
        paidSharesCount:
          type: integer
          description: Number of paid shares
          format: int64
          example: 46
        type:
          type: string
          description: Type of post
          example: post
      description: Instagram Specific Content Report Insights
      allOf:
      - $ref: '#/components/schemas/ContentReportData'
    TwitterContentReportInsight:
      type: object
      properties:
        commentsCount:
          type: integer
          description: Number of comments
          format: int64
          example: 21
        engagementRatePerImpression:
          type: number
          description: Ratio of engagement to impression as a percentage
          format: double
          example: 65.4
        impressionsCount:
          type: integer
          description: Number of impressions
          format: int64
          example: 277
        likesCount:
          type: integer
          description: Number of likes
          format: int64
          example: 65
        quotePostsCount:
          type: integer
          description: Number of reposts
          format: int64
          example: 45
        repostsCount:
          type: integer
          description: Number of reposts
          format: int64
          example: 23
        videoViewsCount:
          type: integer
          description: Number of video views
          format: int64
          example: 73
      description: Twitter Specific Content Report Insights
      allOf:
      - $ref: '#/components/schemas/ContentReportData'
    ContentReportInsight_1:
      required:
      - data
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ContentReportData'
      description: List of content report insight
    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'
    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'
    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'
    TiktokCommunityManagementAction:
      type: object
      allOf:
      - $ref: '#/components/schemas/CommunityManagementAction'
      - type: object
        properties:
          removedCount:
            type: integer
            description: Number of items removed
            format: int64
            example: 5
    FacebookContentReportInsight:
      type: object
      properties:
        angryCount:
          type: integer
          description: Number of angry (reaction)
          format: int64
          example: 830
        clicksCount:
          type: integer
          description: Number of clicks
          format: int64
          example: 830
        commentsCount:
          type: integer
          description: Number of comments
          format: int64
          example: 830
        engagementCount:
          type: integer
          description: Number of engagement
          format: int64
          example: 99
        engagementRatePerView:
          type: number
          description: Ratio of engagement to view as a percentage
          format: double
          example: 25.7
        engagementRatePerReach:
          type: number
          description: Ratio of engagement to reach as a percentage
          format: double
          example: 64.2
        hahaCount:
          type: integer
          description: Number of haha (reaction)
          format: int64
          example: 830
        likeCount:
          type: integer
          description: Number of likes (reaction)
          format: int64
          example: 830
        linkClicksCount:
          type: integer
          description: Number of clicks on links
          format: int64
          example: 752
        loveCount:
          type: integer
          description: Number of love (reaction)
          format: int64
          example: 830
        viewsCount:
          type: integer
          description: Number of views
          format: int64
          example: 245
        organicViewsCount:
          type: integer
          description: Number of organic views
          format: int64
          example: 45
        organicReachCount:
          type: integer
          description: Number of organic reach
          format: int64
          example: 345
        organicVideo30sViewsCount:
          type: integer
          description: The number of times your videos played for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds
          format: int64
          example: 345
        organicVideoCompleteViewsCount:
          type: integer
          description: The number of times your videos played from the beginning to 97%, or more, of its length
          format: int64
          example: 345
        organicVideoCompleteViewViewersCount:
          type: integer
          description: The number of people who viewed your videos from the beginning to 97%, or more, of its length
          format: int64
          example: 345
        otherClicksCount:
          type: integer
          description: Number of other clicks
          format: int64
          example: 836
        paidViewsCount:
          type: integer
          description: Number of paid views
          format: int64
          example: 200
        paidReachCount:
          type: integer
          description: Number of paid reach
          format: int64
          example: 291
        photoViewClicksCount:
          type: integer
          description: Number of clicks to view photos
          format: int64
          example: 918
        paidVideo30sViewsCount:
          type: integer
          description: The number of times your promoted videos played for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds
          format: int64
          example: 918
        paidVideoCompleteViewsCount:
          type: integer
          description: The number of times your promoted videos played from the beginning to 97%, or more, of its length
          format: int64
          example: 918
        paidVideoCompleteViewViewersCount:
          type: integer
          description: The number of people who viewed your promoted videos from the beginning to 97%, or more, of its length
          format: int64
          example: 918
        reachCount:
          type: integer
          description: Number of reach
          format: int64
          example: 1200
        reactionsCount:
          type: integer
          description: Total number of reactions
          format: int64
          example: 1200
        sadCount:
          type: integer
          description: Number of sad (reaction)
          format: int64
          example: 1200
        sharesCount:
          type: integer
          description: Number of shares
          format: int64
          example: 1200
        videoPlaysCount:
          type: integer
          description: Number of video plays
          format: int64
          example: 23
        videoViewsCount:
          type: integer
          description: Number of video views
          format: int64
          example: 23
        organicVideoViewsCount:
          type: integer
          description: Number of organic video views
          format: int64
          example: 3
        paidVideoViewsCount:
          type: integer
          description: Number of paid video views
          format: int64
          example: 20
        videoViewsTimeWatchedCount:
          type: integer
          description: Average viewing time
          format: int64
          example: 12
        videoViewsTimeWatchedRate:
          type: number
          descript

# --- 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