> ## Documentation Index
> Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Base URL: https://api.social-api.ai/v1. Send your API key in the Authorization header: Authorization: Bearer <your API key>.
> Every error response from /v1 is JSON: { "error": { "code", "message", "meta" (optional) }, "request_id" }. Branch on error.code; use error.message only for logs.
> A 429 response carries a Retry-After header, in seconds, when the limit has a known wait. Authenticated responses can carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the per-minute request budget your SocialAPI account shares across every API key (see /guides/rate-limits).
> Paginated list endpoints return next_cursor, at the top level or inside pagination (see /guides/pagination). Pass it as the cursor query parameter to get the next page. An absent or empty next_cursor means you have the last page.
> Treat every ID as an opaque string: do not parse it or assume a format.
> Support differs by platform and by operation. Check /platforms/overview before assuming an operation works on a platform. An unsupported operation returns 501 with error.code resource.not_supported. Some families return their own code instead: reviews, and posts with a target on Telegram or App Store Connect, return 422 account.platform_unsupported; Automations 422 automation.platform_unsupported.

# Get metrics for several posts

> Fetches engagement metrics for up to 20 published posts in one call. Each ID can be a SocialAPI post ID or a platform post ID. Duplicate IDs are returned once.
Each item has the same targets as GET /v1/posts/{post_id}/metrics. A post that cannot be read (not found, or a platform post ID that matches several posts) gets an `error` on its item instead of failing the request.



## OpenAPI

````yaml /api-reference/openapi.json get /posts/metrics
openapi: 3.0.0
info:
  description: >-
    Unified social media inbox API. Read and respond to comments, DMs, reviews,
    and mentions across Instagram, Facebook, Threads, Google Business Profile,
    TikTok, LinkedIn, and YouTube through a single REST API. X/Twitter and
    Trustpilot coming soon.
  title: SocialAPI.AI
  contact:
    name: SocialAPI.AI Support
    email: support@social-api.ai
  license:
    name: MIT
  version: '1.0'
servers:
  - url: https://api.social-api.ai/v1
security: []
paths:
  /posts/metrics:
    get:
      tags:
        - Posts
      summary: Get metrics for several posts
      description: >-
        Fetches engagement metrics for up to 20 published posts in one call.
        Each ID can be a SocialAPI post ID or a platform post ID. Duplicate IDs
        are returned once.

        Each item has the same targets as GET /v1/posts/{post_id}/metrics. A
        post that cannot be read (not found, or a platform post ID that matches
        several posts) gets an `error` on its item instead of failing the
        request.
      operationId: getBatchPostMetrics
      parameters:
        - description: Comma-separated post IDs (SocialAPI or platform), at most 20
          name: post_ids
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostsMetricsResponse'
        '400':
          description: >-
            post_ids missing, more than 20 IDs, or an ID longer than 100
            characters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    PostsMetricsResponse:
      type: object
      required:
        - data
      properties:
        data:
          description: One item per distinct post ID, in request order.
          type: array
          items:
            $ref: '#/components/schemas/PostsMetricsItem'
    ErrorResponse:
      type: object
      required:
        - error
        - request_id
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
        request_id:
          description: >-
            RequestID matches the X-Request-ID response header. Include it when
            contacting support.
          type: string
          example: 01HZ9X3Q4R5M6N7P8V2K0W1J
    PostsMetricsItem:
      type: object
      required:
        - post_id
        - targets
      properties:
        error:
          description: >-
            Set when this post could not be read: not found, or a platform post
            ID that matches several posts.
          allOf:
            - $ref: '#/components/schemas/PostTargetErrorResponse'
        post_id:
          description: The post ID as given in post_ids.
          type: string
          example: 9b2f1c34-5e6a-4d7b-8c9d-0e1f2a3b4c5d
        targets:
          description: >-
            Same targets as GET /v1/posts/{post_id}/metrics. Empty when error is
            set.
          type: array
          items:
            $ref: '#/components/schemas/PostTargetResponse'
    ErrorBody:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: resource.not_found
        message:
          type: string
          example: Account not found
        meta:
          type: object
          additionalProperties: {}
    PostTargetErrorResponse:
      type: object
      required:
        - category
        - caused_by
        - code
        - message
      properties:
        category:
          description: The kind of error. Empty when the error has no category.
          allOf:
            - $ref: '#/components/schemas/PostTargetErrorCategory'
          example: validation
        caused_by:
          description: Who caused the error. Empty when the error has no category.
          allOf:
            - $ref: '#/components/schemas/PostTargetErrorCause'
          example: user
        code:
          type: string
          example: platform.tiktok.media_required
        message:
          type: string
          example: Video posts require at least one media URL
    PostTargetResponse:
      type: object
      required:
        - platform
        - status
      properties:
        account_id:
          type: string
          example: acc_01HZ9X3Q4R5M6N7P8V2K0W1J
        board_id:
          type: string
          example: '8828'
        error:
          $ref: '#/components/schemas/PostTargetErrorResponse'
        first_comment:
          type: string
        media:
          type: array
          items:
            $ref: '#/components/schemas/MediaInput'
        media_ids:
          description: 'Deprecated: use media.'
          type: array
          items:
            type: string
        media_type:
          description: >-
            The kind of post, for example feed, reel, stories or carousel. Other
            values can appear.
          type: string
          example: reel
        metadata:
          type: object
          additionalProperties: {}
        metrics:
          $ref: '#/components/schemas/PostTargetMetricsResponse'
        metrics_synced_at:
          type: string
          format: date-time
          example: '2026-04-01T12:00:00Z'
        page_id:
          type: string
          example: sapi_page_01HZ9X3Q4R5M6N7P8V2K0W1J
        permalink:
          type: string
          example: https://www.instagram.com/p/ABC123/
        platform:
          allOf:
            - $ref: '#/components/schemas/Platform'
          example: instagram
        platform_data:
          description: >-
            The platform-specific options set on this target, as sent in
            platform_data when the post was created or last updated. Chain
            continuation posts are returned in segments, not here.
          type: object
          additionalProperties: {}
        platform_media:
          description: >-
            Every image and video Instagram or Facebook reports on the published
            post: carousel slides or album photos in order, with a cover image
            for each video. The links are temporary: download the files rather
            than keeping the links, and call POST /v1/accounts/{account_id}/sync
            to get fresh ones. Absent on Facebook link and share posts and on
            other platforms.
          type: array
          items:
            $ref: '#/components/schemas/PlatformMediaItem'
        platform_post_id:
          type: string
          example: '17895695668004550'
        published_at:
          type: string
          format: date-time
          example: '2026-04-01T10:00:05Z'
        scheduled_at:
          type: string
          format: date-time
          example: '2026-04-01T10:00:00Z'
        settings:
          description: >-
            Publish settings Instagram or Facebook reports for the published
            post, such as the AI info label, alt text, tagged place or audience
            targeting. Absent when the platform reported none.
          allOf:
            - $ref: '#/components/schemas/PostSettings'
        status:
          allOf:
            - $ref: '#/components/schemas/PostTargetStatus'
          example: published
        text:
          type: string
        title:
          type: string
        visibility:
          type: string
          example: public
    PostTargetErrorCategory:
      type: string
      enum:
        - validation
        - auth
        - rate_limit
        - platform
        - system
        - resource
        - billing
        - account
        - conflict
        - ''
      x-enum-varnames:
        - PostTargetErrorCategoryValidation
        - PostTargetErrorCategoryAuth
        - PostTargetErrorCategoryRateLimit
        - PostTargetErrorCategoryPlatform
        - PostTargetErrorCategorySystem
        - PostTargetErrorCategoryResource
        - PostTargetErrorCategoryBilling
        - PostTargetErrorCategoryAccount
        - PostTargetErrorCategoryConflict
        - PostTargetErrorCategoryNone
    PostTargetErrorCause:
      type: string
      enum:
        - user
        - platform
        - system
        - internal
        - ''
      x-enum-varnames:
        - PostTargetErrorCauseUser
        - PostTargetErrorCausePlatform
        - PostTargetErrorCauseSystem
        - PostTargetErrorCauseInternal
        - PostTargetErrorCauseNone
    MediaInput:
      type: object
      required:
        - source
        - source_type
      properties:
        source:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        source_type:
          allOf:
            - $ref: '#/components/schemas/MediaSourceType'
          example: media_id
        type:
          description: 'The kind of file: image, video, audio or file.'
          type: string
          example: image
    PostTargetMetricsResponse:
      type: object
      required:
        - comments
        - likes
        - saves
        - shares
      properties:
        avg_watch_time_ms:
          description: Average time a viewer spent watching the video, in milliseconds.
          type: integer
          example: 7400
        calls:
          description: Taps on the profile's call button.
          type: integer
          example: 2
        comments:
          type: integer
          example: 23
        crossposted_views:
          description: >-
            Views of the copy shared to another network, for a post shared there
            too.
          type: integer
          example: 310
        directions:
          description: Taps on the profile's directions button.
          type: integer
          example: 1
        emails:
          description: Taps on the profile's email button.
          type: integer
          example: 2
        extra:
          type: object
          additionalProperties: {}
        follows:
          description: Accounts that followed after seeing the post.
          type: integer
          example: 12
        interactions:
          description: >-
            Likes, comments, saves and shares combined, as the platform counts
            them.
          type: integer
          example: 204
        likes:
          type: integer
          example: 142
        profile_actions:
          description: >-
            Actions taken on the account's profile after visiting it from the
            post. website_clicks, calls, directions, emails and texts break it
            down.
          type: integer
          example: 15
        profile_visits:
          description: Visits to the account's profile from the post.
          type: integer
          example: 48
        reach:
          description: Unique accounts that saw the post.
          type: integer
          example: 3870
        reposts:
          description: Times other accounts reposted the post.
          type: integer
          example: 6
        saves:
          type: integer
          example: 31
        shares:
          type: integer
          example: 8
        skip_rate:
          description: Percentage of viewers who skipped the video near its start.
          type: number
          example: 42.5
        texts:
          description: Taps on the profile's text message button.
          type: integer
          example: 1
        total_watch_time_ms:
          description: Total time all viewers spent watching the video, in milliseconds.
          type: integer
          example: 37888000
        views:
          description: Times the post was shown or played.
          type: integer
          example: 5120
        website_clicks:
          description: Clicks on the profile's website link.
          type: integer
          example: 9
    Platform:
      type: string
      enum:
        - app_store_connect
        - bluesky
        - facebook
        - google
        - instagram
        - instagram_fb
        - linkedin
        - linkedin_page
        - pinterest
        - telegram
        - threads
        - tiktok
        - twitter
        - whatsapp
        - youtube
        - zalo
      x-enum-varnames:
        - PlatformAppStoreConnect
        - PlatformBluesky
        - PlatformFacebook
        - PlatformGoogle
        - PlatformInstagram
        - PlatformInstagramFB
        - PlatformLinkedIn
        - PlatformLinkedInPage
        - PlatformPinterest
        - PlatformTelegram
        - PlatformThreads
        - PlatformTikTok
        - PlatformTwitter
        - PlatformWhatsApp
        - PlatformYouTube
        - PlatformZalo
    PlatformMediaItem:
      type: object
      required:
        - type
      properties:
        thumbnail_url:
          description: >-
            Link to a video's cover image, hosted by the platform. Temporary,
            like url. Absent on images.
          type: string
          example: https://scontent.cdninstagram.com/v/t51.29350-15/456_n.jpg
        type:
          description: image or video.
          allOf:
            - $ref: '#/components/schemas/PlatformMediaType'
          example: image
        url:
          description: >-
            Link to the file, hosted by the platform. Temporary: download the
            file rather than keeping the link. Absent when the platform
            withholds the file, as Instagram does for media with licensed audio.
          type: string
          example: https://scontent.cdninstagram.com/v/t51.29350-15/123_n.jpg
    PostSettings:
      type: object
      properties:
        alt_text:
          description: Image description set on the Instagram post.
          type: string
        audio_type:
          description: >-
            Kind of audio on an Instagram Reel, for example MUSIC or
            ORIGINAL_SOUND. Other values can appear.
          type: string
          example: ORIGINAL_SOUND
        child_attachments:
          description: Cards of a Facebook multi-link post.
          type: array
          items:
            $ref: '#/components/schemas/PostChildAttachment'
        comments_enabled:
          description: True when comments are open on the Instagram post.
          type: boolean
        countries:
          description: ISO 3166-1 alpha-2 countries the Facebook post is restricted to.
          type: array
          items:
            type: string
          example:
            - FR
            - BE
        cta_link:
          description: Call-to-action destination on the Facebook post.
          type: string
        cta_type:
          description: Call-to-action button type on the Facebook post.
          type: string
          example: SHOP_NOW
        is_ai_generated:
          description: True when Instagram shows the AI info label on the post.
          type: boolean
        max_age:
          description: Maximum audience age set on the Facebook post.
          type: integer
          example: 65
        min_age:
          description: Minimum audience age set on the Facebook post.
          type: integer
          example: 18
        multi_share_end_card:
          description: True when the multi-link post shows an end card.
          type: boolean
        multi_share_optimized:
          description: True when Facebook picks the card order.
          type: boolean
        place:
          description: Location tagged on the Facebook post.
          allOf:
            - $ref: '#/components/schemas/PostPlace'
        product_type:
          description: >-
            Instagram surface the post lives on, for example FEED, REELS, STORY
            or AD. Other values can appear.
          type: string
          example: REELS
        share_to_feed:
          description: True when an Instagram Reel also appears in the main profile feed.
          type: boolean
    PostTargetStatus:
      type: string
      enum:
        - pending
        - publishing
        - published
        - failed
        - cancelled
        - unpublished
      x-enum-varnames:
        - PostTargetStatusPending
        - PostTargetStatusPublishing
        - PostTargetStatusPublished
        - PostTargetStatusFailed
        - PostTargetStatusCancelled
        - PostTargetStatusUnpublished
    MediaSourceType:
      type: string
      enum:
        - url
        - media_id
        - platform_attachment_id
      x-enum-varnames:
        - MediaSourceTypeURL
        - MediaSourceTypeMediaID
        - MediaSourceTypePlatformAttachmentID
    PlatformMediaType:
      type: string
      enum:
        - image
        - video
      x-enum-varnames:
        - PlatformMediaTypeImage
        - PlatformMediaTypeVideo
    PostChildAttachment:
      type: object
      required:
        - link
      properties:
        description:
          description: Description text of the card.
          type: string
        link:
          description: Destination URL of the card.
          type: string
        name:
          description: Title of the card.
          type: string
        picture:
          description: Image URL of the card.
          type: string
    PostPlace:
      type: object
      required:
        - id
      properties:
        id:
          description: Platform id of the tagged place.
          type: string
        name:
          description: Name of the tagged place.
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.