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

# Instagram Engagement

> Calculate engagement from one current page of public Instagram posts and the account follower count. Ratios are not percentages. Unknown counts and invalid publication times remain null.

Calculate engagement from one current page of public Instagram posts and the account follower count. Ratios are not percentages. Unknown counts and invalid publication times remain null.

A successful uncached call costs **5 credits**. Engagement requires both profile and posts; if either is unavailable, the request fails and is refunded.

Rates are decimal ratios: 0.05 means 5%. The view-based rate uses `(likes + comments + available shares) / views`; absent shares remain null in the post and are excluded from the numerator. The follower-based rate uses `(likes + comments) / followers`. Each average includes only eligible sampled posts. Facebook likes represent total source reactions. Photo-only Instagram posts have no view count.

Cadence is `(dated posts - 1) / days between the oldest and newest sampled posts`, including pinned posts. The measured window and dated sample size are returned. Missing and future timestamps are excluded; velocity is cumulative likes/comments divided by post age, not a measured hourly change. The top post is ranked by follower-based engagement within this page. Unknown lifetime post counts stay null.


## OpenAPI

````yaml GET /instagram/engagement
openapi: 3.1.0
info:
  title: SocialQuery API
  version: '2026-10-09'
  description: >-
    Documented requests for public-source records. Inspect accepted inputs and
    credit amounts, then verify the selected operation before integrating
    preview coverage.
servers:
  - url: https://socialquery.dev/v1
security:
  - apiKey: []
paths:
  /instagram/engagement:
    get:
      tags:
        - Instagram
      summary: Instagram Engagement
      description: >-
        Calculate engagement from one current page of public Instagram posts and
        the account follower count. Ratios are not percentages. Unknown counts
        and invalid publication times remain null.
      operationId: get_instagram_engagement
      parameters:
        - name: handle
          in: query
          required: true
          example: mrbeast
          schema:
            type: string
          description: Public username, optionally prefixed with @.
        - name: Cache-Control
          in: header
          required: false
          example: no-cache
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
          schema:
            type: string
        - name: X-Max-Credits
          in: header
          required: false
          description: >-
            Optional nonnegative integer cap on the maximum request hold. A live
            request whose hold exceeds this cap returns 422
            CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the
            requested limit; cache hits and successful idempotent replays cost
            zero.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: >-
            Calculate engagement from one current page of public Instagram posts
            and the account follower count. Ratios are not percentages. Unknown
            counts and invalid publication times remain null.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          author:
                            type: object
                            required:
                              - id
                              - display_name
                              - followers
                            properties:
                              id:
                                type: string
                                nullable: true
                              username:
                                type: string
                                nullable: true
                              display_name:
                                type: string
                                nullable: true
                              avatar_url:
                                type: string
                                nullable: true
                              bio:
                                type: string
                                nullable: true
                              url:
                                type: string
                                nullable: true
                              external_url:
                                type: string
                                nullable: true
                              location:
                                type: string
                                nullable: true
                              followers:
                                type: number
                                nullable: true
                              following:
                                type: number
                                nullable: true
                              posts_count:
                                type: number
                                nullable: true
                              likes_count:
                                type: number
                                nullable: true
                              verified:
                                type: boolean
                                nullable: true
                              ext:
                                type: object
                          posts:
                            type: array
                            items:
                              type: object
                              properties:
                                post:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    url:
                                      type: string
                                    author:
                                      type: object
                                      required:
                                        - id
                                        - display_name
                                        - followers
                                      properties:
                                        id:
                                          type: string
                                          nullable: true
                                        username:
                                          type: string
                                          nullable: true
                                        display_name:
                                          type: string
                                          nullable: true
                                        avatar_url:
                                          type: string
                                          nullable: true
                                        bio:
                                          type: string
                                          nullable: true
                                        url:
                                          type: string
                                          nullable: true
                                        external_url:
                                          type: string
                                          nullable: true
                                        location:
                                          type: string
                                          nullable: true
                                        followers:
                                          type: number
                                          nullable: true
                                        following:
                                          type: number
                                          nullable: true
                                        posts_count:
                                          type: number
                                          nullable: true
                                        likes_count:
                                          type: number
                                          nullable: true
                                        verified:
                                          type: boolean
                                          nullable: true
                                        ext:
                                          type: object
                                    content:
                                      type: object
                                      properties:
                                        text:
                                          type: string
                                          nullable: true
                                        media_urls:
                                          type: array
                                          items:
                                            type: string
                                        thumbnail_url:
                                          type: string
                                          nullable: true
                                        duration_seconds:
                                          type: number
                                          nullable: true
                                    engagement:
                                      type: object
                                      properties:
                                        views:
                                          type: number
                                          nullable: true
                                        likes:
                                          type: number
                                          nullable: true
                                        comments:
                                          type: number
                                          nullable: true
                                        shares:
                                          type: number
                                          nullable: true
                                        saves:
                                          type: number
                                          nullable: true
                                        reposts:
                                          type: number
                                          nullable: true
                                    flags:
                                      type: object
                                    published_at:
                                      type: string
                                      format: date-time
                                      nullable: true
                                    ext:
                                      type: object
                                      properties:
                                        platform:
                                          type: string
                                        media_type:
                                          type: string
                                          enum:
                                            - image
                                            - video
                                            - carousel
                                            - text
                                            - unknown
                                        carousel_count:
                                          type: number
                                          nullable: true
                                computed:
                                  type: object
                                  properties:
                                    engagement_rate:
                                      type: number
                                      nullable: true
                                    engagement_rate_by_followers:
                                      type: number
                                      nullable: true
                                    likes_per_hour:
                                      type: number
                                      nullable: true
                                    comments_per_hour:
                                      type: number
                                      nullable: true
                          computed:
                            type: object
                            properties:
                              avg_engagement_rate:
                                type: number
                                nullable: true
                              avg_engagement_rate_by_followers:
                                type: number
                                nullable: true
                              sampled_posts:
                                type: number
                                nullable: true
                              view_rate_sample_size:
                                type: number
                                nullable: true
                              follower_rate_sample_size:
                                type: number
                                nullable: true
                              posting_cadence:
                                type: object
                                nullable: true
                                properties:
                                  posts_per_day:
                                    type: number
                                    nullable: true
                                  window_days:
                                    type: number
                                    nullable: true
                                  window_start:
                                    type: string
                                    nullable: true
                                  window_end:
                                    type: string
                                    nullable: true
                                  dated_posts:
                                    type: integer
                              top_post:
                                type: object
                                properties:
                                  post:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                      url:
                                        type: string
                                      author:
                                        type: object
                                        required:
                                          - id
                                          - display_name
                                          - followers
                                        properties:
                                          id:
                                            type: string
                                            nullable: true
                                          username:
                                            type: string
                                            nullable: true
                                          display_name:
                                            type: string
                                            nullable: true
                                          avatar_url:
                                            type: string
                                            nullable: true
                                          bio:
                                            type: string
                                            nullable: true
                                          url:
                                            type: string
                                            nullable: true
                                          external_url:
                                            type: string
                                            nullable: true
                                          location:
                                            type: string
                                            nullable: true
                                          followers:
                                            type: number
                                            nullable: true
                                          following:
                                            type: number
                                            nullable: true
                                          posts_count:
                                            type: number
                                            nullable: true
                                          likes_count:
                                            type: number
                                            nullable: true
                                          verified:
                                            type: boolean
                                            nullable: true
                                          ext:
                                            type: object
                                      content:
                                        type: object
                                        properties:
                                          text:
                                            type: string
                                            nullable: true
                                          media_urls:
                                            type: array
                                            items:
                                              type: string
                                          thumbnail_url:
                                            type: string
                                            nullable: true
                                          duration_seconds:
                                            type: number
                                            nullable: true
                                      engagement:
                                        type: object
                                        properties:
                                          views:
                                            type: number
                                            nullable: true
                                          likes:
                                            type: number
                                            nullable: true
                                          comments:
                                            type: number
                                            nullable: true
                                          shares:
                                            type: number
                                            nullable: true
                                          saves:
                                            type: number
                                            nullable: true
                                          reposts:
                                            type: number
                                            nullable: true
                                      flags:
                                        type: object
                                      published_at:
                                        type: string
                                        format: date-time
                                        nullable: true
                                      ext:
                                        type: object
                                        properties:
                                          platform:
                                            type: string
                                          media_type:
                                            type: string
                                            enum:
                                              - image
                                              - video
                                              - carousel
                                              - text
                                              - unknown
                                          carousel_count:
                                            type: number
                                            nullable: true
                                  computed:
                                    type: object
                                    properties:
                                      engagement_rate:
                                        type: number
                                        nullable: true
                                      engagement_rate_by_followers:
                                        type: number
                                        nullable: true
                                      likes_per_hour:
                                        type: number
                                        nullable: true
                                      comments_per_hour:
                                        type: number
                                        nullable: true
                                nullable: true
                              format_mix:
                                type: object
                                nullable: true
                                additionalProperties:
                                  type: integer
                          _warnings:
                            type: array
                            items:
                              type: string
                          legs:
                            type: array
                            items:
                              type: object
                              properties:
                                endpoint:
                                  type: string
                                status:
                                  type: string
                                  enum:
                                    - ok
                                    - error
                          followers:
                            type: number
                            nullable: true
                          engagement_rate:
                            type: number
                            nullable: true
                          total_likes:
                            type: number
                            nullable: true
                          total_comments:
                            type: number
                            nullable: true
                          sampled_posts:
                            type: number
                            nullable: true
                          engagement_rate_unit:
                            type: string
                            enum:
                              - ratio
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    SocialQueryResponse:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - data
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: >-
            The selected operation determines the resource fields in this
            object. Source data can omit a metric or report it as null.
    SocialQueryError:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - error
      properties:
        success:
          type: boolean
          const: false
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        error:
          type: object
          required:
            - code
            - type
            - message
            - status
            - doc_url
          properties:
            code:
              type: string
            type:
              type: string
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              format: uri
  responses:
    Error400:
      description: Upstream rejected the request.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error401:
      description: Missing, expired, invalid, or revoked API key.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error402:
      description: Insufficient SocialQuery credits.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error403:
      description: Key scope or provider policy denied access.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error404:
      description: Endpoint or upstream resource not found.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error405:
      description: HTTP method is not supported.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error409:
      description: Idempotency conflict or request in progress.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error422:
      description: Invalid parameters.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error429:
      description: Request limit reached.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error500:
      description: Request processing failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error502:
      description: Upstream service failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error503:
      description: Provider or required service is unavailable.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error504:
      description: Upstream service timed out.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

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