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

# Get channel insights

> Returns the insights of one channel for a date range: the metrics it reports, the summary and the metric series for the range and the previous range. Days are calendar days in the API key user's time zone. Labels, untagged and types narrow the post metrics; followers stay account-wide. Channels on LinkedIn, LinkedIn pages, Telegram, Discord and Google Business have no insights and return `404`. With `custom` (or `start`/`end` without `range`), the dates are clamped to the days with data in scope (`bounds`; for a channel, that channel's). When there is no data yet, the dates are ignored and the last 30 days are returned. A missing `end` defaults to the last day with data, and a missing `start` to 29 days before `end`. Read `range` (or `filters.start`/`filters.end`) in the response for the days actually used.



## OpenAPI

````yaml /openapi.json get /channels/{account}/insights
openapi: 3.1.0
info:
  title: TryPost API
  version: 2.0.0
  description: >-
    REST API for TryPost. Authenticate with a workspace API key as a Bearer
    token.
servers:
  - url: https://app.trypost.it/api
    description: TryPost Cloud
security:
  - bearerAuth: []
tags:
  - name: Posts
    description: Create, read, update, delete and preview posts.
  - name: Post notes
    description: Internal notes on a post, visible to workspace members.
  - name: Approvals
    description: Approve or reject posts waiting for approval.
  - name: Recurrence
    description: Make a post repeat on a schedule.
  - name: Media and uploads
    description: Upload files and attach media to posts.
  - name: Social accounts
    description: Connected social accounts and their network-specific options.
  - name: Channels
    description: A channel's posting schedule and queue.
  - name: Ideas
    description: Ideas on the Create board.
  - name: Idea stages
    description: The groups (columns) of the ideas board.
  - name: Analytics
    description: Workspace and channel insights.
  - name: Labels
    description: Labels to organize posts and ideas.
  - name: Signatures
    description: Reusable text to append to posts.
  - name: Workspace
    description: The workspace the API key belongs to.
  - name: API keys
    description: Personal API keys for this workspace.
  - name: Webhooks
    description: Outgoing webhooks and their delivery logs.
  - name: Repurposes
    description: Automations that republish videos posted outside TryPost.
  - name: Platform
    description: Platform capabilities and content types.
paths:
  /channels/{account}/insights:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    get:
      tags:
        - Analytics
      summary: Get channel insights
      description: >-
        Returns the insights of one channel for a date range: the metrics it
        reports, the summary and the metric series for the range and the
        previous range. Days are calendar days in the API key user's time zone.
        Labels, untagged and types narrow the post metrics; followers stay
        account-wide. Channels on LinkedIn, LinkedIn pages, Telegram, Discord
        and Google Business have no insights and return `404`. With `custom` (or
        `start`/`end` without `range`), the dates are clamped to the days with
        data in scope (`bounds`; for a channel, that channel's). When there is
        no data yet, the dates are ignored and the last 30 days are returned. A
        missing `end` defaults to the last day with data, and a missing `start`
        to 29 days before `end`. Read `range` (or `filters.start`/`filters.end`)
        in the response for the days actually used.
      operationId: getChannelInsights
      parameters:
        - name: range
          in: query
          required: false
          description: >-
            `7d` (last 7 days), `30d` (last 30 days, the default), `mtd` (month
            to date) or `custom`. Days are calendar days in the API key user's
            time zone, today included.
          schema:
            type: string
            enum:
              - 7d
              - 30d
              - mtd
              - custom
            default: 30d
        - name: start
          in: query
          required: false
          description: >-
            First day, `Y-m-d`. Required with `range=custom` and ignored for the
            other presets. Sending `start` and `end` without `range` means
            `custom`.
          schema:
            type: string
            format: date
        - name: end
          in: query
          required: false
          description: >-
            Last day, `Y-m-d`, on or after `start`. Required with
            `range=custom`.
          schema:
            type: string
            format: date
        - name: labels[]
          in: query
          required: false
          style: form
          explode: true
          description: >-
            Only posts with any of these labels (labels of this workspace).
            Unknown or deleted labels return `422`.
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: untagged
          in: query
          required: false
          description: >-
            Also (or only) posts without labels. Posts made outside TryPost have
            no labels. Send `1` or `0`; `true` and `false` are rejected with
            `422`.
          schema:
            type: string
            enum:
              - '1'
              - '0'
        - name: types[]
          in: query
          required: false
          style: form
          explode: true
          description: Only these content types. They must belong to the channel's network.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ContentType'
        - name: period
          in: query
          required: false
          description: >-
            Accepted for parity with the post list; only echoed in `filters`
            here.
          schema:
            type: string
            enum:
              - current
              - previous
            default: current
        - name: sort
          in: query
          required: false
          description: >-
            Accepted for parity with the post list; only echoed in `filters`
            here.
          schema:
            type: string
            enum:
              - reactions
              - comments
              - engagement_rate
              - views
              - impressions
              - shares
              - saves
              - reach
      responses:
        '200':
          description: The channel's insights.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelInsights'
              example:
                filters:
                  range: 30d
                  start: '2026-09-09'
                  end: '2026-10-08'
                  period: current
                  sort: reactions
                  labels: []
                  untagged: false
                  types: []
                available_metrics:
                  - followers
                  - net_followers
                  - posts
                  - reactions
                  - comments
                  - engagement_rate
                  - views
                  - impressions
                  - reposts
                  - quotes
                  - clicks
                summary:
                  bounds:
                    min: '2026-04-11'
                    max: '2026-10-08'
                  range:
                    start: '2026-09-09'
                    end: '2026-10-08'
                  previous_range:
                    start: '2026-08-10'
                    end: '2026-09-08'
                  summary:
                    posts:
                      value: 18
                      previous: 15
                      change: 20
                    followers:
                      value: 12480
                      previous: 12160
                      change: 320
                    net_followers:
                      value: 320
                      previous: 250
                      change: 28
                    reactions:
                      value: 2140
                      previous: 1890
                      change: 13.23
                    comments:
                      value: 188
                      previous: 205
                      change: -8.29
                    engagement_rate:
                      value: 4.12
                      previous: 3.85
                      change: 7.01
                    views:
                      value: 48210
                      previous: 39900
                      change: 20.83
                    impressions:
                      value: 61300
                      previous: 52010
                      change: 17.86
                    clicks:
                      value: 512
                      previous: 430
                      change: 19.07
                    reposts:
                      value: 96
                      previous: 80
                      change: 20
                    quotes:
                      value: 12
                      previous: 9
                      change: 33.33
                    reach:
                      value: 30120
                      previous: 27400
                      change: 9.93
                    shares:
                      value: 140
                      previous: 118
                      change: 18.64
                    saves:
                      value: 210
                      previous: 175
                      change: 20
                    watch_time_minutes:
                      value: 1830.5
                      previous: 1502.25
                      change: 21.85
                    average_watch_time_seconds:
                      value: 14.2
                      previous: 12.8
                      change: 10.94
                    follows_gained:
                      value: 41
                      previous: 37
                      change: 10.81
                  followers:
                    total: 12480
                    accounts:
                      - social_account_key: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
                        social_account_id: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
                        platform: x
                        network: x
                        name: TryPost
                        username: trypostit
                        avatar_url: >-
                          https://pbs.twimg.com/profile_images/1790000000000000000/avatar_400x400.jpg
                        value: 12480
                        growth: 320
                        net: 320
                        provenance: provider
                        status: connected
                    series:
                      - date: '2026-10-02'
                        accounts:
                          9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54: 12160
                      - date: '2026-10-08'
                        accounts:
                          9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54: 12480
                  posts:
                    resolution: weekly
                    accounts:
                      - social_account_key: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
                        platform: x
                        name: TryPost
                        username: trypostit
                        avatar_url: >-
                          https://pbs.twimg.com/profile_images/1790000000000000000/avatar_400x400.jpg
                        count: 18
                        status: connected
                    buckets:
                      - start: '2026-09-28'
                        end: '2026-10-04'
                        accounts:
                          9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54: 3
                        total: 3
                  top_posts:
                    reactions:
                      - id: 9d4a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c
                        post_platform_id: 9d3c1f2b-1a2b-4c3d-8e4f-5a6b7c8d9e10
                        post_id: 9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41
                        social_account_key: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
                        platform: x
                        name: TryPost
                        username: trypostit
                        avatar_url: >-
                          https://pbs.twimg.com/profile_images/1790000000000000000/avatar_400x400.jpg
                        origin: trypost
                        content_type: image
                        availability: available
                        published_at: '2026-10-02 14:00:00'
                        permalink: https://x.com/trypostit/status/1841234567890123456
                        excerpt: >-
                          We just shipped scheduled threads. Here is how they
                          work.
                        preview_metadata: null
                        reactions: 412
                        comments: 38
                        status: connected
                    comments:
                      - id: 9d4a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c
                        post_platform_id: 9d3c1f2b-1a2b-4c3d-8e4f-5a6b7c8d9e10
                        post_id: 9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41
                        social_account_key: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
                        platform: x
                        name: TryPost
                        username: trypostit
                        avatar_url: >-
                          https://pbs.twimg.com/profile_images/1790000000000000000/avatar_400x400.jpg
                        origin: trypost
                        content_type: image
                        availability: available
                        published_at: '2026-10-02 14:00:00'
                        permalink: https://x.com/trypostit/status/1841234567890123456
                        excerpt: >-
                          We just shipped scheduled threads. Here is how they
                          work.
                        preview_metadata: null
                        reactions: 412
                        comments: 38
                        status: connected
                  performance:
                    - social_account_key: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
                      platform: x
                      name: TryPost
                      username: trypostit
                      avatar_url: >-
                        https://pbs.twimg.com/profile_images/1790000000000000000/avatar_400x400.jpg
                      posts:
                        value: 18
                        previous: 15
                        change: 20
                      reactions:
                        value: 2140
                        previous: 1890
                        change: 13.23
                      comments:
                        value: 188
                        previous: 205
                        change: -8.29
                      engagement_rate:
                        value: 4.12
                        previous: 3.85
                        change: 7.01
                      reposts:
                        value: 96
                        previous: 80
                        change: 20
                      impressions:
                        value: 61300
                        previous: 52010
                        change: 17.86
                      clicks:
                        value: 512
                        previous: 430
                        change: 19.07
                      views:
                        value: 48210
                        previous: 39900
                        change: 20.83
                      shares:
                        value: 140
                        previous: 118
                        change: 18.64
                      saves:
                        value: 210
                        previous: 175
                        change: 20
                      follows_gained:
                        value: 41
                        previous: 37
                        change: 10.81
                      reach:
                        value: 30120
                        previous: 27400
                        change: 9.93
                      watch_time_minutes:
                        value: 1830.5
                        previous: 1502.25
                        change: 21.85
                      average_watch_time_seconds:
                        value: 14.2
                        previous: 12.8
                        change: 10.94
                      status: connected
                  coverage:
                    - social_account_id: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
                      collector: publication_backfill
                      status: complete
                      target_since: '2026-04-11T00:00:00.000000Z'
                      oldest_reached_at: '2026-04-11T09:12:00.000000Z'
                      high_watermark_at: '2026-10-08T06:00:00.000000Z'
                      last_success_at: '2026-10-08T06:00:00.000000Z'
                      last_error_category: null
                metric_series:
                  resolution: daily
                  metrics:
                    - posts
                    - followers
                    - net_followers
                    - views
                    - impressions
                  range:
                    start: '2026-09-09'
                    end: '2026-10-08'
                  previous_range:
                    start: '2026-08-10'
                    end: '2026-09-08'
                  current:
                    - start: '2026-09-09'
                      end: '2026-09-09'
                      values:
                        posts: 1
                        followers: 12160
                        net_followers: 4
                        views: 2300
                        impressions: 2900
                  previous:
                    - start: '2026-08-10'
                      end: '2026-08-10'
                      values:
                        posts: 0
                        followers: 11900
                        net_followers: 3
                        views: 0
                        impressions: 0
                  totals:
                    current:
                      posts: 18
                      followers: 12480
                      net_followers: 320
                      views: 48210
                      impressions: 61300
                    previous:
                      posts: 15
                      followers: 12160
                      net_followers: 250
                      views: 39900
                      impressions: 52010
                  growth:
                    range:
                      start: '2025-11-01'
                      end: '2026-10-08'
                    months:
                      - month: 2026-10
                        start: '2026-10-01'
                        end: '2026-10-08'
                        followers: 12480
                        rate: 1.4
                    latest: 1.4
                    previous: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    AccountId:
      name: account
      in: path
      required: true
      description: >-
        Social account (channel) id. An account of another workspace returns
        `404`.
      schema:
        type: string
        format: uuid
      example: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54
  schemas:
    ContentType:
      type: string
      enum:
        - instagram_feed
        - instagram_reel
        - instagram_story
        - linkedin_post
        - linkedin_page_post
        - facebook_post
        - facebook_reel
        - facebook_story
        - tiktok_video
        - tiktok_photo
        - youtube_short
        - x_post
        - threads_post
        - threads_ghost_post
        - pinterest_pin
        - pinterest_video_pin
        - pinterest_carousel
        - bluesky_post
        - mastodon_post
        - telegram_post
        - discord_message
        - google_business_post
      description: >-
        Post format on one network. It must belong to the destination's network.
        `GET /content-types` lists the formats of each network with their media
        rules. Instagram and Facebook stories publish no text.
    ChannelInsights:
      type: object
      properties:
        filters:
          $ref: '#/components/schemas/ChannelInsightsFilters'
        available_metrics:
          type: array
          items:
            type: string
          description: >-
            Metrics this channel reports, in display order (`followers`,
            `net_followers`, `posts`, `reactions`, `comments`,
            `engagement_rate`, `views`, `impressions`, `shares`, `reposts`,
            `quotes`, `saves`, `clicks`, `follows_gained`, `reach`,
            `watch_time_minutes`, `average_watch_time_seconds`).
        summary:
          $ref: '#/components/schemas/WorkspaceAnalyticsReport'
          description: >-
            The workspace report shape, limited to this channel. Labels,
            untagged and types narrow the post metrics; followers stay
            account-wide.
        metric_series:
          type: object
          description: >-
            Per-bucket series for the range and the previous range. `posts`,
            `reach`, `views`, `impressions` and `profile_visits` are totals of
            the posts published in each bucket, not daily account totals.
            `followers` is the count at the end of each bucket; `net_followers`
            is cumulative from the start of the range.
          properties:
            resolution:
              type: string
              enum:
                - daily
                - weekly
              description: >-
                Daily up to 92 days, weekly beyond (weeks start on the API key
                user's start of week).
            metrics:
              type: array
              items:
                type: string
                enum:
                  - posts
                  - followers
                  - net_followers
                  - reach
                  - views
                  - impressions
                  - profile_visits
            range:
              $ref: '#/components/schemas/AnalyticsDateRange'
            previous_range:
              $ref: '#/components/schemas/AnalyticsDateRange'
            current:
              type: array
              items:
                type: object
                properties:
                  start:
                    type: string
                    format: date
                  end:
                    type: string
                    format: date
                  values:
                    type: object
                    additionalProperties:
                      type:
                        - number
                        - 'null'
                    description: Value of each metric in `metrics` for the bucket.
            previous:
              type: array
              items:
                type: object
                properties:
                  start:
                    type: string
                    format: date
                  end:
                    type: string
                    format: date
                  values:
                    type: object
                    additionalProperties:
                      type:
                        - number
                        - 'null'
                    description: Value of each metric in `metrics` for the bucket.
            totals:
              type: object
              properties:
                current:
                  type: object
                  additionalProperties:
                    type:
                      - number
                      - 'null'
                previous:
                  type: object
                  additionalProperties:
                    type:
                      - number
                      - 'null'
            growth:
              type:
                - object
                - 'null'
              description: >-
                Monthly follower growth rate for the last 12 months. Ignores the
                range and the post filters. `null` until TryPost has at least
                two daily follower counts for the channel.
              properties:
                range:
                  $ref: '#/components/schemas/AnalyticsDateRange'
                months:
                  type: array
                  items:
                    type: object
                    properties:
                      month:
                        type: string
                        examples:
                          - 2026-10
                      start:
                        type: string
                        format: date
                      end:
                        type: string
                        format: date
                      followers:
                        type:
                          - integer
                          - 'null'
                      rate:
                        type:
                          - number
                          - 'null'
                latest:
                  type:
                    - number
                    - 'null'
                  description: Latest non-null monthly growth rate, in percent.
                previous:
                  type:
                    - number
                    - 'null'
                  description: Previous non-null monthly growth rate, in percent.
    ChannelInsightsFilters:
      type: object
      description: The filters the server applied, after defaults.
      properties:
        range:
          type: string
          enum:
            - 7d
            - 30d
            - mtd
            - custom
        start:
          type: string
          format: date
        end:
          type: string
          format: date
        period:
          type: string
          enum:
            - current
            - previous
        sort:
          type: string
          description: >-
            The sort used: the requested one when the channel reports that
            metric, else the first sortable metric it reports.
        labels:
          type: array
          items:
            type: string
            format: uuid
        untagged:
          type: boolean
        types:
          type: array
          items:
            $ref: '#/components/schemas/ContentType'
    WorkspaceAnalyticsReport:
      type: object
      properties:
        bounds:
          type: object
          description: >-
            First and last day with analytics data in scope (`null` when there
            is none).
          properties:
            min:
              type:
                - string
                - 'null'
              format: date
            max:
              type:
                - string
                - 'null'
              format: date
        range:
          $ref: '#/components/schemas/AnalyticsDateRange'
        previous_range:
          $ref: '#/components/schemas/AnalyticsDateRange'
        summary:
          $ref: '#/components/schemas/AnalyticsSummary'
        followers:
          type: object
          properties:
            total:
              type:
                - integer
                - 'null'
              description: >-
                `null` when a connected channel in scope has no follower count
                for the range yet.
            accounts:
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/AnalyticsAccountRef'
                  - type: object
                    properties:
                      social_account_id:
                        type:
                          - string
                          - 'null'
                        format: uuid
                      network:
                        type: string
                      value:
                        type:
                          - integer
                          - 'null'
                        description: Followers at the end of the range.
                      growth:
                        type:
                          - integer
                          - 'null'
                        description: >-
                          Followers gained between the first and last snapshot
                          of the range.
                      net:
                        type:
                          - integer
                          - 'null'
                        description: >-
                          Net followers gained in the range, when the network
                          reports it.
                      provenance:
                        type:
                          - string
                          - 'null'
            series:
              type: array
              description: >-
                One point per day: follower count of each channel, keyed by
                `social_account_key`.
              items:
                type: object
                properties:
                  date:
                    type: string
                    format: date
                  accounts:
                    type: object
                    additionalProperties:
                      type:
                        - integer
                        - 'null'
        posts:
          type: object
          properties:
            resolution:
              type: string
              enum:
                - daily
                - weekly
                - monthly
              description: >-
                Daily up to 14 days, weekly up to 90 days, monthly beyond. Weeks
                start on the API key user's start of week.
            accounts:
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/AnalyticsAccountRef'
                  - type: object
                    properties:
                      count:
                        type: integer
                        description: Posts published in the range.
              description: Channels with at least one post in the range.
            buckets:
              type: array
              items:
                type: object
                properties:
                  start:
                    type: string
                    format: date
                  end:
                    type: string
                    format: date
                  accounts:
                    type: object
                    additionalProperties:
                      type: integer
                    description: Posts per channel, keyed by `social_account_key`.
                  total:
                    type: integer
        top_posts:
          type: object
          description: >-
            Up to 5 posts of the range with the most reactions, and up to 5 with
            the most comments.
          properties:
            reactions:
              type: array
              items:
                $ref: '#/components/schemas/AnalyticsTopPost'
            comments:
              type: array
              items:
                $ref: '#/components/schemas/AnalyticsTopPost'
        performance:
          type: array
          description: >-
            One row per channel with at least one post in the range, with each
            metric compared with the previous range.
          items:
            allOf:
              - $ref: '#/components/schemas/AnalyticsAccountRef'
              - type: object
                properties:
                  posts:
                    $ref: '#/components/schemas/MetricComparison'
                  reactions:
                    $ref: '#/components/schemas/MetricComparison'
                  comments:
                    $ref: '#/components/schemas/MetricComparison'
                  engagement_rate:
                    $ref: '#/components/schemas/MetricComparison'
                  reposts:
                    $ref: '#/components/schemas/MetricComparison'
                  impressions:
                    $ref: '#/components/schemas/MetricComparison'
                  clicks:
                    $ref: '#/components/schemas/MetricComparison'
                  views:
                    $ref: '#/components/schemas/MetricComparison'
                  shares:
                    $ref: '#/components/schemas/MetricComparison'
                  saves:
                    $ref: '#/components/schemas/MetricComparison'
                  follows_gained:
                    $ref: '#/components/schemas/MetricComparison'
                  reach:
                    $ref: '#/components/schemas/MetricComparison'
                  watch_time_minutes:
                    $ref: '#/components/schemas/MetricComparison'
                  average_watch_time_seconds:
                    $ref: '#/components/schemas/MetricComparison'
        coverage:
          type: array
          description: >-
            How far back analytics have been collected for each connected
            channel. Each channel can have one row per collector.
          items:
            type: object
            properties:
              social_account_id:
                type: string
                format: uuid
              collector:
                type: string
                enum:
                  - publication_backfill
                  - publication_discovery
              status:
                type: string
                enum:
                  - pending
                  - running
                  - complete
                  - partial
                  - provider_limited
                  - failed
              target_since:
                type:
                  - string
                  - 'null'
                format: date-time
                description: >-
                  ISO 8601, UTC, with microseconds
                  (`2026-04-11T00:00:00.000000Z`).
              oldest_reached_at:
                type:
                  - string
                  - 'null'
                format: date-time
                description: >-
                  ISO 8601, UTC, with microseconds
                  (`2026-04-11T00:00:00.000000Z`).
              high_watermark_at:
                type:
                  - string
                  - 'null'
                format: date-time
                description: >-
                  ISO 8601, UTC, with microseconds
                  (`2026-04-11T00:00:00.000000Z`).
              last_success_at:
                type:
                  - string
                  - 'null'
                format: date-time
                description: >-
                  ISO 8601, UTC, with microseconds
                  (`2026-04-11T00:00:00.000000Z`).
              last_error_category:
                type:
                  - string
                  - 'null'
    AnalyticsDateRange:
      type: object
      description: Calendar days in the API key user's time zone (both ends included).
      properties:
        start:
          type: string
          format: date
        end:
          type: string
          format: date
    ErrorBody:
      type: object
      properties:
        message:
          type: string
    ValidationErrorBody:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    RateLimitErrorBody:
      type: object
      properties:
        name:
          type: string
          const: rate_limit_exceeded
        message:
          type: string
          examples:
            - Rate limit exceeded. Please retry after 30 seconds.
    AnalyticsSummary:
      type: object
      description: >-
        Totals for the range compared with the previous range. `posts` counts
        posts published in the range (made in TryPost or not). `engagement_rate`
        is a percent. `watch_time_minutes` and `average_watch_time_seconds`
        cover videos.
      properties:
        posts:
          $ref: '#/components/schemas/MetricComparison'
        net_followers:
          $ref: '#/components/schemas/MetricComparison'
        reactions:
          $ref: '#/components/schemas/MetricComparison'
        comments:
          $ref: '#/components/schemas/MetricComparison'
        engagement_rate:
          $ref: '#/components/schemas/MetricComparison'
        views:
          $ref: '#/components/schemas/MetricComparison'
        impressions:
          $ref: '#/components/schemas/MetricComparison'
        clicks:
          $ref: '#/components/schemas/MetricComparison'
        reposts:
          $ref: '#/components/schemas/MetricComparison'
        quotes:
          $ref: '#/components/schemas/MetricComparison'
        reach:
          $ref: '#/components/schemas/MetricComparison'
        shares:
          $ref: '#/components/schemas/MetricComparison'
        saves:
          $ref: '#/components/schemas/MetricComparison'
        watch_time_minutes:
          $ref: '#/components/schemas/MetricComparison'
        average_watch_time_seconds:
          $ref: '#/components/schemas/MetricComparison'
        follows_gained:
          $ref: '#/components/schemas/MetricComparison'
        followers:
          type: object
          description: >-
            Followers at the end of the range. Unlike the other metrics,
            `change` is the difference in followers, not a percent. `value` is
            `null` when a connected channel in scope has no follower count for
            the range yet.
          properties:
            value:
              type:
                - integer
                - 'null'
            previous:
              type:
                - integer
                - 'null'
            change:
              type:
                - integer
                - 'null'
    AnalyticsAccountRef:
      type: object
      description: Identity of a channel in an analytics row.
      properties:
        social_account_key:
          type: string
          description: >-
            Stable analytics key of the channel. For a connected channel it is
            the social account id.
        platform:
          $ref: '#/components/schemas/Platform'
        name:
          type:
            - string
            - 'null'
        username:
          type:
            - string
            - 'null'
        avatar_url:
          type:
            - string
            - 'null'
        status:
          type:
            - string
            - 'null'
          enum:
            - connected
            - disconnected
            - token_expired
            - null
          description: >-
            Current connection status. `null` when the channel is no longer in
            the workspace.
    AnalyticsTopPost:
      allOf:
        - $ref: '#/components/schemas/AnalyticsAccountRef'
        - type: object
          properties:
            id:
              type: string
              format: uuid
              description: >-
                Analytics publication id. Read its detail with `GET
                /analytics/publications/{publication}`.
            post_platform_id:
              type:
                - string
                - 'null'
              format: uuid
            post_id:
              type:
                - string
                - 'null'
              format: uuid
              description: TryPost post, or `null` for a post made outside TryPost.
            origin:
              type: string
              description: '`trypost` or `external`.'
            content_type:
              type:
                - string
                - 'null'
              description: Analytics publication type (`text`, `image`, `video`, ...).
            availability:
              type: string
            published_at:
              type:
                - string
                - 'null'
              description: When the network published it, UTC, `Y-m-d H:i:s`.
            permalink:
              type:
                - string
                - 'null'
            excerpt:
              type:
                - string
                - 'null'
            preview_metadata:
              type:
                - object
                - 'null'
            reactions:
              type:
                - integer
                - 'null'
            comments:
              type:
                - integer
                - 'null'
    MetricComparison:
      type: object
      description: A metric for the range and for the previous range of the same length.
      properties:
        value:
          type:
            - number
            - 'null'
          description: >-
            Value for the range. `null` when no channel in scope reports this
            metric.
        previous:
          type:
            - number
            - 'null'
          description: Value for the previous range.
        change:
          type:
            - number
            - 'null'
          description: >-
            Percent change from `previous` to `value`, rounded to 2 decimals.
            `null` when either is `null` or `previous` is 0.
    Platform:
      type: string
      enum:
        - linkedin
        - linkedin-page
        - x
        - tiktok
        - youtube
        - facebook
        - instagram
        - instagram-facebook
        - threads
        - pinterest
        - bluesky
        - mastodon
        - telegram
        - discord
        - google_business
      description: >-
        Network of a social account. `linkedin-page` is a LinkedIn company page,
        `instagram-facebook` an Instagram account connected through a Facebook
        Page.
  responses:
    Unauthorized:
      description: >-
        Missing, invalid, revoked or expired API key. Bodies: `Unauthenticated.`
        (no key, or a key that is invalid or revoked), `Token expired.` (past
        its `expires_at`), `Token not found.` and `No workspace selected.` (the
        key is no longer bound to a workspace).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            message: Unauthenticated.
    PaymentRequired:
      description: >-
        TryPost Cloud only: the workspace's account has no active subscription
        or trial. Body: `{"message": "Active subscription required."}`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            message: Active subscription required.
    Forbidden:
      description: >-
        The request is not allowed. API keys work only for workspace admins (the
        account owner or a member marked as admin): otherwise every request
        returns `Insufficient workspace permissions.`. Other bodies: `Workspace
        access denied.` (the key's user left the workspace) and `Personal access
        token required.` (an MCP OAuth token was sent) and `This action is
        unauthorized.` (the note belongs to another member).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
    NotFound:
      description: The resource does not exist in this workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
    ValidationError:
      description: Validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorBody'
    TooManyRequests:
      description: 'Rate limit exceeded. Limits: 60 requests per minute per workspace.'
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitErrorBody'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Workspace API key from Settings → API Keys.

````

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