> ## Documentation Index
> Fetch the complete documentation index at: https://postflow.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Posts analytics
> Returns paginated performance metrics for individual posts within the specified date range. Includes aggregate sums and averages.
## OpenAPI
````yaml /public/api.json get /analytics/content/posts
openapi: 3.1.0
info:
title: PostFlow
version: '1'
description: >-
The PostFlow API gives you access to analytics data from your PostFlow
organization and provides you with tools for scheduling and publishing
social media posts directly from your own application, automation tool, or
AI assistant.
### What is PostFlow?
PostFlow is a social media management platform designed to help teams and
creators plan, collaborate, and publish social media content.
### Base URL
The base URL for the PostFlow API is:
```http
https://api.postflow.app/v1
```
For media requests use base URL:
```http
https://media.postflow.app/api/v1
```
### Authentication
All API requests require a bearer token in the Authorization header.
You can generate an API token from your [PostFlow account
settings](https://new.postflow.app/settings/account/api). Once you have your
token, include it in the Authorization header of your API requests as
follows:
```http
Authorization: Bearer YOUR_API_TOKEN
```
### Headers
API requests must include the following headers:
```http
Accept: application/json
Content-Type: application/json
```
### Make your first request
Once you have a token, you can make requests directly to the API. The
following example returns basic information about your organization:
```bash
curl https://api.postflow.app/v1/organizations \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"
```
## Rate limits
The PostFlow API implements rate limiting to ensure fair usage and protect
against abuse. The default limit is **60 requests per minute** per
authenticated user.
Each API response includes the following headers with information about your
current rate limit status:
- `X-RateLimit-Limit` - maximum number of requests allowed per minute
- `X-RateLimit-Remaining` - number of requests remaining in the current
window
- `X-RateLimit-Reset` - Unix timestamp when the rate limit resets
## PostFlow IDs
Every object in the PostFlow API has a unique ID. PostFlow uses a system
called "Snowflake ID" created by Twitter.
These IDs are **64-bit unsigned integers**. Some programming languages
(JavaScript) cannot accurately represent 64-bit integers.
> **Warning:** You must **ALWAYS** use strings for PostFlow IDs in your
code.
### String vs integer in Javascript
In JavaScript, integers are limited to 53 bits. This causes precision loss
with large IDs:
```javascript
// This loses precision!
const id = 10765432100123456789;
console.log(id.toString()); // "10765432100123458000" — wrong!
// Use strings instead
const id = "10765432100123456789";
console.log(id); // "10765432100123456789" — correct!
```
### Comparing IDs
Examples of how you can compare PostFlow IDs:
```javascript javascript
// Use BigInt
if (BigInt(post1.id) > BigInt(post2.id)) {
console.log("post1 is newer");
}
```
```python python
# Python handles large integers natively
if post1.id > post2.id:
print("post1 is newer")
```
```php php
# PHP is safe with 64-bit integers
if (post1->id > post2->id) {
dd("post1 is newer");
}
```
## Relationships & includes
Some endpoints support the `include` query parameter to enrich the response
with related resources. Pass a comma-separated list of relationship names to
load them alongside the primary data.
```http
GET /posts?include=media
```
Multiple relationships can be included by separating them with a comma:
```http
GET /posts?include=media,labels,postComments
```
## OpenAPI collection
The raw OpenAPI specifications for the PostFlow API are available below.
They can be used with various API tools and code generators that support the
OpenAPI format.
- [PostFlow API](https://postflow.app/docs/public/api.json)
- [Media API](https://postflow.app/docs/public/media.json)
> You can copy the above URLs to import them into API tools such as Postman.
servers:
- url: https://api.postflow.app/v1
security:
- http: []
tags:
- name: User
- name: Organization
- name: Social accounts
- name: Posts
- name: Posts bulk
- name: Post activities
- name: Post metrics
- name: Analytics
- name: Widgets
- name: Calendar notes
- name: Groups
- name: Labels
paths:
/analytics/content/posts:
get:
tags:
- Analytics
summary: Posts analytics
description: >-
Returns paginated performance metrics for individual posts within the
specified date range. Includes aggregate sums and averages.
operationId: analytics.contentPosts
parameters:
- name: start
in: query
required: true
schema:
type: string
format: date-time
example: '2026-01-19T09:00:00.000Z'
- name: end
in: query
required: true
schema:
type: string
format: date-time
example: '2026-06-14T09:00:00.000Z'
- name: groupId
in: query
required: true
schema:
type: number
- name: socialAccountIds[]
in: query
schema:
type:
- array
- 'null'
items:
type: string
- name: compareTo
in: query
schema:
type:
- string
- 'null'
enum:
- period
- year
- null
- name: postTypes[]
in: query
description: Omit to get them all.
schema:
type: array
items:
$ref: '#/components/schemas/PostType'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AnalyticsContentPost'
links:
type: array
items: {}
meta:
type: object
properties:
current_page:
type: integer
first_page_url:
type:
- string
- 'null'
from:
type:
- integer
- 'null'
last_page:
type: integer
last_page_url:
type:
- string
- 'null'
next_page_url:
type:
- string
- 'null'
path:
type:
- string
- 'null'
per_page:
type: integer
prev_page_url:
type:
- string
- 'null'
to:
type:
- integer
- 'null'
total:
type: integer
required:
- current_page
- first_page_url
- from
- last_page
- last_page_url
- next_page_url
- path
- per_page
- prev_page_url
- to
- total
sum:
$ref: '#/components/schemas/PostMetricBaseData'
avg:
$ref: '#/components/schemas/PostMetricBaseData'
required:
- data
- links
- meta
- sum
- avg
'401':
$ref: '#/components/responses/AuthenticationException'
'422':
$ref: '#/components/responses/ValidationException'
components:
schemas:
PostType:
type: string
enum:
- text
- link
- image
- video
- short
- carousel
- poll
- story
- audio
- document
- gallery
x-enum-varnames:
- Text
- Link
- Image
- Video
- Short
- Carousel
- Poll
- Story
- Audio
- Document
- Gallery
title: PostType
AnalyticsContentPost:
type: object
properties:
postTitle:
type:
- string
- 'null'
content:
type:
- string
- 'null'
postLink:
type:
- string
- 'null'
mediaCount:
type:
- integer
- 'null'
firstMedia:
anyOf:
- $ref: '#/components/schemas/MediaData'
- type: 'null'
postType:
anyOf:
- $ref: '#/components/schemas/PostType'
- type: 'null'
postMetric:
$ref: '#/components/schemas/PostMetricData'
required:
- postTitle
- content
- postLink
- mediaCount
- firstMedia
- postType
- postMetric
title: AnalyticsContentPost
PostMetricBaseData:
type: object
properties:
score:
type:
- number
- 'null'
views:
type:
- number
- 'null'
reach:
type:
- number
- 'null'
likes:
type:
- number
- 'null'
dislikes:
type:
- number
- 'null'
shares:
type:
- number
- 'null'
quotes:
type:
- number
- 'null'
replies:
type:
- number
- 'null'
saves:
type:
- number
- 'null'
follows:
type:
- number
- 'null'
user_profile_clicks:
type:
- number
- 'null'
post_link_clicks:
type:
- number
- 'null'
post_other_clicks:
type:
- number
- 'null'
engagements:
type:
- number
- 'null'
engagement_rate_impressions:
type:
- number
- 'null'
engagement_rate_reach:
type:
- number
- 'null'
video_views:
type:
- number
- 'null'
video_watch_time_total:
type:
- number
- 'null'
video_watch_time_avg:
type:
- number
- 'null'
poll_votes:
type:
- integer
- 'null'
required:
- score
- views
- reach
- likes
- dislikes
- shares
- quotes
- replies
- saves
- follows
- user_profile_clicks
- post_link_clicks
- post_other_clicks
- engagements
- engagement_rate_impressions
- engagement_rate_reach
- video_views
- video_watch_time_total
- video_watch_time_avg
- poll_votes
title: PostMetricBaseData
MediaData:
type: object
properties:
id:
type: string
organization_id:
type: string
user_id:
type:
- string
- 'null'
description: The ID of the user who uploaded the media
media_folder_id:
type:
- string
- 'null'
is_media_library:
type: boolean
description: Determines whether the media is part of the media library
type:
$ref: '#/components/schemas/MediaType'
url:
type: string
client_name:
type:
- string
- 'null'
file_name:
type: string
mime_type:
type: string
extension:
type: string
size:
type: integer
thumbnail:
type:
- string
- 'null'
preview:
type:
- string
- 'null'
width:
type:
- integer
- 'null'
height:
type:
- integer
- 'null'
aspect_ratio:
type:
- number
- 'null'
duration:
type:
- number
- 'null'
fps:
type:
- number
- 'null'
video_thumbnail_frame:
type:
- string
- 'null'
video_thumbnail_custom:
type:
- string
- 'null'
video_thumbnail_time:
type:
- number
- 'null'
page_count:
type:
- integer
- 'null'
description: Number of pages in the PDF document
page_previews:
type: array
items:
type: string
conversions:
type:
- array
- 'null'
items:
type: string
alt_text:
type:
- string
- 'null'
pivot_alt_text:
type:
- array
- 'null'
items:
type: string
note:
type:
- string
- 'null'
origin:
anyOf:
- $ref: '#/components/schemas/MediaOrigin'
- type: 'null'
is_processing:
type: boolean
is_converted:
type: boolean
description: >-
The media has been converted to ensure compatibility with social
platforms
created_at:
type:
- string
- 'null'
format: date-time
updated_at:
type:
- string
- 'null'
format: date-time
required:
- id
- organization_id
- user_id
- media_folder_id
- is_media_library
- type
- url
- client_name
- file_name
- mime_type
- extension
- size
- thumbnail
- preview
- width
- height
- aspect_ratio
- duration
- fps
- video_thumbnail_frame
- video_thumbnail_custom
- video_thumbnail_time
- page_count
- page_previews
- conversions
- alt_text
- pivot_alt_text
- note
- origin
- is_processing
- is_converted
- created_at
- updated_at
title: MediaData
PostMetricData:
type: object
properties:
id:
type: string
post_id:
type:
- string
- 'null'
post_detail_id:
type: string
social_account_id:
type:
- string
- 'null'
social_post_id:
type:
- string
- 'null'
score:
type:
- number
- 'null'
description: |-
Each post receives a score from 0 to 10.
The score is based on 60% engagements and 40% impressions.
More info: https://postflow.app/blog/postflow-analytics#post-score
views:
type:
- integer
- 'null'
reach:
type:
- integer
- 'null'
likes:
type:
- integer
- 'null'
dislikes:
type:
- integer
- 'null'
shares:
type:
- integer
- 'null'
quotes:
type:
- integer
- 'null'
replies:
type:
- integer
- 'null'
saves:
type:
- integer
- 'null'
follows:
type:
- integer
- 'null'
user_profile_clicks:
type:
- integer
- 'null'
post_link_clicks:
type:
- integer
- 'null'
post_other_clicks:
type:
- integer
- 'null'
engagements:
type:
- integer
- 'null'
engagement_rate_impressions:
type:
- number
- 'null'
engagement_rate_reach:
type:
- number
- 'null'
video_views:
type:
- integer
- 'null'
video_watch_time_total:
type:
- integer
- 'null'
video_watch_time_avg:
type:
- integer
- 'null'
score_1:
type:
- integer
- 'null'
score_2:
type:
- integer
- 'null'
score_3:
type:
- integer
- 'null'
score_4:
type:
- integer
- 'null'
score_5:
type:
- integer
- 'null'
score_6:
type:
- integer
- 'null'
score_7:
type:
- integer
- 'null'
score_8:
type:
- integer
- 'null'
score_9:
type:
- integer
- 'null'
score_10:
type:
- integer
- 'null'
updated_at:
type: string
format: date-time
published_at:
type:
- string
- 'null'
format: date-time
poll_results:
type:
- array
- 'null'
items:
type: string
poll_votes:
type:
- integer
- 'null'
postDetail:
anyOf:
- $ref: '#/components/schemas/PostDetailData'
- type: 'null'
items:
type: array
description: Used for Stories posts. Each story has its own item with metrics
default: []
items:
$ref: '#/components/schemas/PostMetricData'
required:
- id
- post_id
- post_detail_id
- social_account_id
- social_post_id
- score
- views
- reach
- likes
- dislikes
- shares
- quotes
- replies
- saves
- follows
- user_profile_clicks
- post_link_clicks
- post_other_clicks
- engagements
- engagement_rate_impressions
- engagement_rate_reach
- video_views
- video_watch_time_total
- video_watch_time_avg
- score_1
- score_2
- score_3
- score_4
- score_5
- score_6
- score_7
- score_8
- score_9
- score_10
- updated_at
- published_at
- poll_results
- poll_votes
- postDetail
- items
title: PostMetricData
MediaType:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
x-enum-varnames:
- Image
- Video
- Audio
- Document
- Subtitles
description: >-
`1` Image
`2` Video
`3` Audio
`4` Document
`5`
Subtitles
title: MediaType
MediaOrigin:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
x-enum-varnames:
- Import
- ClickUp
- GoogleDrive
- Dropbox
- Tenor
- PostComment
- Api
- ExternalSync
description: >-
`1` Import
`2` ClickUp
`3` GoogleDrive
`4` Dropbox
`5` Tenor
`6` PostComment
`7` Api
`8`
ExternalSync
title: MediaOrigin
PostDetailData:
type: object
properties:
id:
type: string
social_network:
$ref: '#/components/schemas/SocialNetwork'
post_type:
anyOf:
- $ref: '#/components/schemas/PostType'
- type: 'null'
post_id:
type: string
social_account_id:
type: string
enabled:
type: boolean
is_customized:
type: boolean
status:
$ref: '#/components/schemas/PostStatus'
stories:
type:
- array
- 'null'
items:
type: string
is_story:
type: boolean
published_at:
type:
- string
- 'null'
format: date-time
user_error_message:
type:
- string
- 'null'
content:
type:
- string
- 'null'
link_preview:
$ref: '#/components/schemas/PostLinkPreview'
post_link:
type:
- string
- 'null'
firstComment:
anyOf:
- $ref: '#/components/schemas/PostFirstCommentData'
- type: 'null'
required:
- id
- social_network
- post_type
- post_id
- social_account_id
- enabled
- is_customized
- status
- stories
- is_story
- published_at
- user_error_message
- content
- link_preview
- post_link
- firstComment
title: PostDetailData
SocialNetwork:
type: string
enum:
- twitter
- linkedin
- linkedin_page
- facebook
- instagram
- tiktok
- bluesky
- pinterest
- google_business_profile
- youtube
- threads
- snapchat
- dribbble
- tumblr
x-enum-varnames:
- Twitter
- LinkedIn
- LinkedInPage
- FacebookPage
- Instagram
- TikTok
- Bluesky
- Pinterest
- GoogleBusinessProfile
- YouTube
- Threads
- Snapchat
- Dribbble
- Tumblr
title: SocialNetwork
PostStatus:
type: integer
enum:
- 1
- 5
- 10
- 15
- 20
- 25
- 30
- 35
- 37
- 40
- 50
x-enum-varnames:
- NotSchedule
- Draft
- InReview
- ReviewRejected
- ReviewMissed
- Scheduled
- InProgress
- Failed
- Skipped
- Published
- Deleted
description: >-
`1` NotSchedule
`5` Draft
`10` InReview
`15`
ReviewRejected
`20` ReviewMissed
`25` Scheduled
`30`
InProgress
`35` Failed
`37` Skipped
`40` Published
`50` Deleted
title: PostStatus
PostLinkPreview:
type: object
properties:
url:
type:
- string
- 'null'
host:
type:
- string
- 'null'
title:
type:
- string
- 'null'
description:
type:
- string
- 'null'
image_url:
type:
- string
- 'null'
required:
- url
- host
- title
- description
- image_url
title: PostLinkPreview
PostFirstCommentData:
type: object
properties:
id:
type: string
condition_type:
anyOf:
- $ref: '#/components/schemas/PostCondition'
- type: 'null'
condition_value:
type: integer
publishing_failed:
type: boolean
user_error_message:
type:
- string
- 'null'
published_at:
type:
- string
- 'null'
format: date-time
created_at:
type:
- string
- 'null'
format: date-time
required:
- id
- condition_type
- condition_value
- publishing_failed
- user_error_message
- published_at
- created_at
title: PostFirstCommentData
PostCondition:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
x-enum-varnames:
- Delay
- Likes
- Replies
- Shares
- Views
description: >-
`1` Delay
`2` Likes
`3` Replies
`4` Shares
`5`
Views
title: PostCondition
responses:
AuthenticationException:
description: Unauthenticated
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error overview.
required:
- message
ValidationException:
description: Validation error
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Errors overview.
errors:
type: object
description: A detailed description of each field that failed validation.
additionalProperties:
type: array
items:
type: string
required:
- message
- errors
securitySchemes:
http:
type: http
scheme: bearer
````