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

# Get Analytics

> Get the latest post metrics and audience counts for one Mallary profile.

Use `profile_id` to read analytics for a non-default connection profile. Omit it to read analytics for the default profile.

The response has two lists:

* `data.analytics` has the latest metrics for recent posts. Use `post_id` to limit this list to one post.
* `data.audience` has the latest saved follower or subscriber count for each connected account in the profile. It uses the same fields and statuses as [Get Audience Counts](https://docs.mallary.ai/api-reference/endpoint/audience.md). The `post_id` filter does not change this list.

To search, filter, sort, and page through every post group, use [Browse Post Analytics](https://docs.mallary.ai/api-reference/endpoint/analytics-posts.md).

Mallary updates supported audience counts once every 24 hours. TikTok follower counts become available after a connection grants `user.info.stats` and Mallary saves its first count. Existing connections without that permission return `permission_required` for their audience count. They keep working as before.

Metrics keep the meaning supplied by each platform. Impressions, reach, and views are separate measurements. A metric the platform did not supply is `null`, while a reported zero remains `0`. Check `captured_at` and `metric_window` to see when Mallary saved a metric and whether it covers a lifetime or rolling period.

`engagementRate` remains a ratio for existing API clients. `engagementRatePercent` is the same value shown as a percentage. `engagementRateDenominator` names the base used for the calculation when a rate is available.

If an older LinkedIn connection needs the analytics permission, the response uses `status: "reconnect_required"` and says `Reconnect to get analytics`. Reconnect LinkedIn once from the Platforms page. Mallary will then start collecting those post results.


## OpenAPI

````yaml GET /api/v1/analytics
openapi: 3.0.3
info:
  title: Mallary API
  version: 1.6.0
  description: >
    Public API for multi-platform publishing, analytics, media upload, and
    webhooks.


    Authentication:

    - Use header `Authorization: Bearer {api_key}`.

    - API key identity is authoritative. Do not use `user_id` to identify a
    caller.


    Connection profiles:

    - Omit `profile_id` to use the authenticated user's default profile.

    - Send the profile's random public `profile_id` when you want to publish,
    list posts, read post analytics or audience counts, list platforms, update
    settings, or disconnect a platform for a non-default profile.

    - Use `GET /api/v1/profiles` to list profile IDs.

    - Total social media accounts: Starter 5 ($15/month), Pro 15 ($29/month),
    Business 100 ($95/month). Posts are unlimited. Scheduling, analytics, and AI
    auto-replies are included. X publishing and comments use credits at cost;
    analytics and account lookups use no credits. Existing customers keep their
    current terms; use the authenticated workspace limits.


    Rate limits (per user, per minute) depend on subscription plan:

    - plan_id 1: 75 req/min

    - plan_id 2: 150 req/min

    - plan_id 3: 750 req/min

    - plan_id 4: 1500 req/min
servers:
  - url: https://mallary.ai
    description: Production
security:
  - bearerAuth: []
externalDocs:
  description: Full product docs
  url: https://docs.mallary.ai/
paths:
  /api/v1/analytics:
    get:
      summary: Get latest post metrics and audience counts
      description: >-
        Returns the latest per-platform post metrics in `data.analytics` and the
        latest saved follower or subscriber counts in `data.audience`. Audience
        counts use the same fields and statuses as GET /api/v1/audience and
        cover every connected account in the selected profile. Mallary refreshes
        supported audience counts once every 24 hours. TikTok follower counts
        become available after a connection grants `user.info.stats` and Mallary
        saves its first count. Existing connections without that permission
        return `permission_required` for their audience count and keep working
        as before.
      operationId: listAnalytics
      parameters:
        - in: query
          name: post_id
          required: false
          schema:
            type: integer
          description: >-
            Filter post metrics to a single post/job ID owned by the
            authenticated user. Audience counts still cover the whole selected
            profile.
        - in: query
          name: profile_id
          required: false
          schema:
            $ref: '#/components/schemas/ProfileId'
          description: >-
            Select the connection profile for both post metrics and audience
            counts. Omit to use the default profile.
      responses:
        '200':
          description: Analytics retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - ok
                  data:
                    type: object
                    properties:
                      profile_id:
                        type: string
                        pattern: ^[A-Za-z0-9]{6,32}$
                        nullable: true
                      analytics:
                        type: array
                        items:
                          $ref: '#/components/schemas/AnalyticsItem'
                      audience:
                        type: array
                        description: >-
                          Latest saved audience count and collection status for
                          each connected account in the selected profile. This
                          list is not filtered by `post_id`.
                        items:
                          $ref: '#/components/schemas/AudienceItem'
        '401':
          description: Missing or invalid API key
        '403':
          description: >-
            Analytics are not available for current plan, or supplied `user_id`
            does not match API key owner
        '404':
          description: Post not found
components:
  schemas:
    ProfileId:
      type: string
      pattern: ^[A-Za-z0-9]{6,32}$
      example: AbC123xYz90
      description: Random public connection profile ID returned by `GET /api/v1/profiles`.
    AnalyticsItem:
      allOf:
        - type: object
          properties:
            post_id:
              type: integer
            platform:
              $ref: '#/components/schemas/Platform'
            status:
              type: string
              enum:
                - available
                - reconnect_required
            status_message:
              type: string
              nullable: true
            reconnect_required:
              type: boolean
        - $ref: '#/components/schemas/AnalyticsMetrics'
    AudienceItem:
      type: object
      required:
        - platform
        - label
        - account
        - metric
        - count
        - status
      properties:
        platform:
          $ref: '#/components/schemas/PublicPlatform'
        label:
          type: string
        account:
          $ref: '#/components/schemas/AudienceAccount'
        metric:
          $ref: '#/components/schemas/AudienceMetric'
        count:
          type: integer
          format: int64
          minimum: 0
          nullable: true
        status:
          $ref: '#/components/schemas/AudienceStatus'
        status_message:
          type: string
          nullable: true
        captured_at:
          type: string
          format: date-time
          nullable: true
        last_attempt_at:
          type: string
          format: date-time
          nullable: true
        next_update_at:
          type: string
          format: date-time
          nullable: true
    Platform:
      type: string
      description: Supported publishing platform identifier.
      enum:
        - twitter
        - x
        - facebook
        - instagram
        - linkedin
        - youtube
        - tiktok
        - pinterest
        - reddit
        - threads
        - bluesky
    AnalyticsMetrics:
      type: object
      properties:
        captured_at:
          type: string
          format: date-time
          nullable: true
        impressions:
          type: integer
          nullable: true
        reach:
          type: integer
          nullable: true
        likes:
          type: integer
          nullable: true
        comments:
          type: integer
          nullable: true
        shares:
          type: integer
          nullable: true
        clicks:
          type: integer
          nullable: true
        views:
          type: integer
          nullable: true
        saves:
          type: integer
          nullable: true
        bookmarks:
          type: integer
          nullable: true
        outbound_clicks:
          type: integer
          nullable: true
        pin_clicks:
          type: integer
          nullable: true
        url_clicks:
          type: integer
          nullable: true
        profile_clicks:
          type: integer
          nullable: true
        engaged_users:
          type: integer
          nullable: true
        engagementRate:
          type: number
          nullable: true
          description: >-
            Interaction rate as a ratio, retained for API compatibility. Use the
            denominator field to interpret it.
        engagementRatePercent:
          type: number
          nullable: true
          description: The same interaction rate as a percentage.
        engagementRateDenominator:
          type: string
          nullable: true
          enum:
            - views
            - impressions
            - reach
        metric_window:
          type: string
          nullable: true
          enum:
            - lifetime
            - rolling_30d
            - rolling_90d
        metric_semantics_version:
          type: integer
          nullable: true
    PublicPlatform:
      type: string
      description: >-
        Canonical public platform identifier used in connected-platform
        listings.
      enum:
        - x
        - facebook
        - instagram
        - linkedin
        - youtube
        - tiktok
        - pinterest
        - reddit
        - threads
        - bluesky
    AudienceAccount:
      type: object
      properties:
        id:
          type: string
          nullable: true
        username:
          type: string
          nullable: true
        avatar_url:
          type: string
          format: uri
          nullable: true
    AudienceMetric:
      type: string
      enum:
        - followers
        - subscribers
        - page_likes
    AudienceStatus:
      type: string
      enum:
        - available
        - collecting
        - permission_required
        - reconnect_required
        - unsupported
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Use `Authorization: Bearer {api_key}`'

````

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