---
title: "List Posts and Metrics"
method: POST
path: "/v1/analytics/posts"
tags: ["Analytics"]
---

# List Posts and Metrics

`POST /v1/analytics/posts`

## Request

- Base URL: `https://platform.hootsuite.com`
- URL: `https://platform.hootsuite.com/v1/analytics/posts`
- Auth: OAuth 2
  - Authorization code: `https://platform.hootsuite.com/oauth2/auth`
  - Token URL: `https://platform.hootsuite.com/oauth2/token`

Fetch posts that have been published on this Social Network, including lifetime metrics for each post.
`profileId` is a required filter, the others are optional. `lastModified` may start at most 30 days in the past.  `reportingPeriod` may start at most 2 years in the past.
When filtering by `reportingPeriod`, the creation date of the post is used.

## Query parameters

- `datatype` 'ORGANIC' | 'PAID': API code for this datatype
- `networkId` 'FACEBOOKPAGE' | 'TWITTER' | 'INSTAGRAMBUSINESS' | 'TIKTOKBUSINESS' | 'YOUTUBECHANNEL' | 'PINTEREST' | 'THREADS': API code for this Social Network
- `cursor` string
- `limit` integer

## Request body

- ListPostsRequest
  - `filters` RequestFilters, required
    - `profileId` DataFieldFilters, required: Filter by a data field, at least one filter must be specified.
      - `eq` string: Filter by exact match.
      - `in` string[]: Options to filter against, at least 1 must match.
    - `lastModified` TimeFieldFilters: Filter by a time field, at least one filter must be specified.
      - `timespan` TimespanFilter: Timespan to filter against, inclusive. At least one of `since` or `until` must be provided.
        - `since` string, date: Start of query, if omitted defaults to 1 year ago
        - `until` string, date: End of query, if omitted defaults to now
    - `reportingPeriod` TimeFieldFilters: Filter by a time field, at least one filter must be specified.
      - `timespan` TimespanFilter: Timespan to filter against, inclusive. At least one of `since` or `until` must be provided.
        - `since` string, date: Start of query, if omitted defaults to 1 year ago
        - `until` string, date: End of query, if omitted defaults to now

## Response `200`

Posts returned.

- ListPostsResponse
  - `data` Post[], required
    - `createdAt` string, datetime, required: timestamp when the post was published.
    - `lastRefreshed` string, datetime: timestamp when post data was last refreshed.
    - `profileId` string, required: Hootsuite identifier of the social profile for this post.
    - `externalProfileId` string, required: Identifier of the social profile on the social network this post is associated with.
    - `sourceLink` string, required: URL of the post on the social network.
    - `externalId` string, required: Post ID from the social network.
    - `createdMember` Author
      - `id` string
      - `name` string
      - `photo` string
      - `url` string
      - `displayName` string
      - `location` string
    - `campaign` LabeledType
      - `label` string, required
      - `id` string, required
    - `detectedViralAt` string, datetime: timestamp when the post was detected as viral.
    - `isViral` boolean
    - `tags` LabeledType[]
      - `label` string, required
      - `id` string, required
    - `links` LinkPublic[]
      - `extendedUrl` string
      - `thumbnailUrl` string
    - `media` MediaPublic[]
      - `mimeType` 'MEDIA_UNKNOWN' | 'MEDIA_PHOTO' | 'MEDIA_VIDEO' | 'MEDIA_ANIMATED_GIF' | 'MEDIA_TEXT' | 'MEDIA_LINK' | 'MEDIA_SWF' | 'MEDIA_MUSIC' | 'MEDIA_OFFER' | 'MEDIA_ALBUM' | 'MEDIA_EVENT' | 'MEDIA_NOTE' | 'MEDIA_AUDIO'
      - `thumbnailUrl` string: Omit when high_resolution_thumbnail_url is present.
      - `url` string
      - `liveVideo` boolean
      - `length` integer
      - `title` string
      - `content` string
      - `highResolutionThumbnailUrl` string
    - `attachmentTypes` AttachmentType[]
    - `title` string: Post title.
    - `content` string: Post content.
    - `metrics` MetricsPublic: All social network and Owly metrics in a single map. Keys are metric names (e.g. "likes", "comments", "post_views", "clicks"). Values are numeric (float64). For metric definitions, see the Help Center documentation.
    - `postType` string: Post type from the social network (e.g. FACEBOOK_VIDEO, TWITTER_RETWEET, INSTAGRAM_REEL).
    - `metadata` PostMetadata: Platform-specific metadata in a single object. Keys and values depend on social_profile_type. Examples: is_popular, object_type, is_boosted_post, is_eligible_for_promotion (Facebook); in_reply_to_status_id, in_reply_to_user_id (Twitter); embed_url, video_duration (TikTok). Excluded from source data: in_reply_to_link, quote_to_post_id, user_mentions (Twitter); board_id (Pinterest).
    - `source` Author
      - `id` string
      - `name` string
      - `photo` string
      - `url` string
      - `displayName` string
      - `location` string
    - `autoTags` LabeledType[]
      - `label` string, required
      - `id` string, required
  - `metadata` Metadata, required
    - `collectionInfo` CollectionInfo, required
      - `next` Cursor
        - `cursor` string, required: Cursor for the next/prev page of data, if available
      - `prev` Cursor
        - `cursor` string, required: Cursor for the next/prev page of data, if available

## Other responses

- `default`: An error occurred.

---

[API](https://skmtc.dev/hootsuite/apis/hootsuite-rest-api.md) - [All operations](https://skmtc.dev/hootsuite/apis/hootsuite-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hootsuite/apis/hootsuite-rest-api/revisions/adac53bd28bb?raw)