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

# Facebook Profile Full

> Combine the public profile with one page of recent posts. Returns sampled engagement ratios, cadence with an explicit window, top post and format mix. The profile is required; post-source failure returns status=partial with post-dependent metrics null.

Combine the public profile with one page of recent posts. Returns sampled engagement ratios, cadence with an explicit window, top post and format mix. The profile is required; post-source failure returns status=partial with post-dependent metrics null.

A successful uncached call costs **5 credits**. A post-source failure preserves the valid profile as an explicit partial result at the same flat price. Read `legs` and `_warnings`.

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.

One source page is normally 10 TikTok, 12 Instagram or 3 Facebook posts. `posts` can shorten it but cannot fetch more pages. A truncation discards the rest of that page; `posts_cursor` advances beyond the whole source page. Pass it with the same account identity. `include=computed` omits raw post rows without changing the calculation.


## OpenAPI

````yaml GET /facebook/profile/full
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:
  /facebook/profile/full:
    get:
      tags:
        - Facebook
      summary: Facebook Profile Full
      description: >-
        Combine the public profile with one page of recent posts. Returns
        sampled engagement ratios, cadence with an explicit window, top post and
        format mix. The profile is required; post-source failure returns
        status=partial with post-dependent metrics null.
      operationId: get_facebook_profile_full
      parameters:
        - name: url
          in: query
          required: false
          example: https://www.facebook.com/mrbeast
          schema:
            type: string
        - name: posts
          in: query
          required: false
          example: 25
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: >-
            Truncate the single source page to this size. Does not fetch
            additional pages; continuation advances beyond the entire upstream
            page.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Pass posts_cursor with the same account identity; bound to
            platform/account. Each new page costs 5 credits.
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - posts
              - computed
              - posts,computed
              - computed,posts
          description: >-
            CSV subset of posts,computed; both by default. Computation still
            reads the same page.
        - 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: >-
            Combine the public profile with one page of recent posts. Returns
            sampled engagement ratios, cadence with an explicit window, top post
            and format mix. The profile is required; post-source failure returns
            status=partial with post-dependent metrics 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
                          posts_cursor:
                            type: string
                            nullable: true
                          has_more:
                            type: boolean
                          status:
                            type: string
                            enum:
                              - complete
                              - partial
                          metric_definitions:
                            type: object
        '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.