Posts API¶

The Posts API provides unified access to social media posts across all supported platforms in a single endpoint.

Overview¶

The /posts endpoint combines posts from Facebook, Instagram, TikTok, YouTube, LinkedIn, Threads, Snapchat, Dailymotion, and Pinterest into a unified format, making it easy to access content from multiple platforms with a single API call.

Each post in the response contains only the metrics relevant to its specific platform. For example, a Facebook post will only show Facebook-specific metrics, not YouTube metrics.

Get All Posts¶

GET /posts

Retrieve posts from all accessible social media platforms with all metrics in a unified format.

Parameters¶

Parameter	Type	Required	Description
`limit`	integer	No	Maximum number of posts to return (default: 10, max: 50)
`cursor`	string	No	Cursor for pagination. Use the `next_cursor` value from the previous response to get the next page.
`platform`	string	No	Filter by platform(s). Use comma-separated values like `fb,ig,tk,yt,li,th,sc,da,pi` or `facebook,instagram,tiktok,youtube,linkedin,threads,snapchat,dailymotion,pinterest`
`since`	string	No	Filter posts created after this date (YYYY-MM-DD format)
`until`	string	No	Filter posts created before this date (YYYY-MM-DD format)
`order_by`	string	No	Order posts by specified field. Valid values: `interactions`, `revenue`, `reach`, `views`, `created_time`. If not specified, defaults to `created_time` descending.
`order`	string	No	Sort order direction. Valid values: `asc`, `desc`. Default: `desc`.
`post_type`	string	No	Filter by post type(s). Use comma-separated values like `video,image,reel`. Valid values: `video`, `image`, `share`, `text`, `carousel`, `reel`, `document`. If not specified, returns all post types.
`brand_id`	string	No	Brand identifier(s). Single ID or comma-separated IDs (e.g., 1 or 1,2,3). If neither brand_id nor account_id is provided, defaults to all accessible brands.
`account_id`	string	No	Account identifier(s). Single ID or comma-separated IDs (e.g., 4 or 4,2). Can be used instead of brand_id or together with it. When provided, automatically resolves to brand_id(s) for access control. account_id values require exactly one platform to be specified.

Platform Aliases¶

Platform	Aliases
Facebook	`facebook`, `fb`
Instagram	`instagram`, `ig`
TikTok	`tiktok`, `tk`
YouTube	`youtube`, `yt`
LinkedIn	`linkedin`, `li`
Threads	`threads`, `th`
Snapchat	`snapchat`, `sc`
Dailymotion	`dailymotion`, `da`
Pinterest	`pinterest`, `pi`

Example Requests¶

Get all posts (default):

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/posts/"

Get posts from specific platforms:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/posts/?platform=facebook,instagram,tiktok"

Get posts with custom limit and ordering:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/posts/?limit=25&platform=yt,li&order_by=created_time&order=desc"

Get posts with date filters:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/posts/?since=2024-01-01&until=2024-12-31"

Get posts with pagination:

# First request
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/posts/?limit=10"

# Use next_cursor from response for next page
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/posts/?limit=10&cursor=eyJpZCI6MTIzLCJjcmVhdGVkX3RpbWUiOiIyMDI0LTAxLTE1VDEwOjMwOjAwWiJ9"

Get specific type of posts:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/posts/?post_type=story,image"

Get specific brand posts:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/posts/?brand_id=1"

Get specific account posts:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/posts/?account_id=1,2&platform=fb"

Response Format¶

{
  "posts": [
    {
      "id": 123456,
      "platform": "facebook",
      "created_time": "2024-01-15T10:30:00Z",
      "description": "Post content here...",
      "title": "Post Title",
      "type": "video_inline",
      "account_id": 4,
      "account_name": "Page Name",
      "total_interactions": 169,
      "revenue": 0.0,
      "reach": 13144,
      "views": 24231,
      "duration": 20.16,
      "subjects": "topic1, topic2",
      "category": "Category > Subcategory",
      "social_pulse": -1.46,
      "likes": 31,
      "shares": 40,
      "video_views": 8356,
      "total_time_watched": 120000,
      "average_time_watched": 14.36
    },
    {
      "id": 789012,
      "platform": "instagram",
      "created_time": "2024-01-15T10:25:00Z",
      "description": "Instagram post caption...",
      "title": null,
      "type": "REELS",
      "account_id": 2,
      "account_name": "Account Name",
      "total_interactions": 250.5,
      "revenue": null,
      "views": 4800,
      "duration": 15.0,
      "subjects": null,
      "category": null,
      "social_pulse": 2.5,
      "likes": 200,
      "shares": 10,
      "saved": 50,
      "average_time_watched": 12.5,
      "total_time_watched": 60000
    }
  ],
  "total_count": 2,
  "facebook_count": 1,
  "instagram_count": 1,
  "tiktok_count": 0,
  "youtube_count": 0,
  "linkedin_count": 0,
  "threads_count": 0,
  "snapchat_count": 0,
  "dailymotion_count": 0,
  "pinterest_count": 0,
  "limit_applied": 10,
  "next_cursor": "eyJpZCI6Nzg5MDEyLCJjcmVhdGVkX3RpbWUiOiIyMDI0LTAxLTE1VDEwOjI1OjAwWiJ9"
}

Response Fields¶

Common Fields (All Platforms)¶

All posts include these common fields:

id - Internal database record ID
platform - Platform type (facebook, instagram, tiktok, youtube, linkedin, threads, snapchat, dailymotion, pinterest)
created_time - Date and time when the post was created
description - Post content/caption
title - Post title (may be null)
type - Content/media type (e.g., video_inline, REELS, Tk_VIDEO, etc.)
account_id - Account/page/channel ID
account_name - Account/page/channel name
total_interactions - Total interactions (sum of likes, comments, shares, etc.)
revenue - Revenue generated (may be null for some platforms)
reach - Lifetime reach (may be null for some platforms)
views - Total number of views
duration - Content duration in seconds (may be null)
subjects - Subjects/labels associated with the post (may be null, requires topics=true)
category - Category associated with the post (may be null, requires category=true)
total_time_watched - Total time watched in seconds (may be null for some platforms)
average_time_watched - Average time watched in seconds (may be null for some platforms)
social_pulse - Social pulse score (score_distribution)
likes - Number of likes
comments - Number of comments (may be excluded for some platforms)
shares - Number of shares

Platform-Specific Metrics¶

Each platform includes additional metrics specific to that platform.

Important: Each post only contains metrics relevant to its specific platform. For example, a Facebook post will only show Facebook-specific metrics, not YouTube metrics.

Pagination¶

The endpoint uses cursor-based pagination, which is more efficient than offset-based pagination for large datasets. The response includes a next_cursor field when there are more posts available. Use this cursor value in the cursor query parameter to fetch the next page.

How it works: 1. Make your first request without a cursor parameter 2. If the response includes a next_cursor field, use that value in your next request 3. Continue until next_cursor is null or not present

Example:

# First page - no cursor needed
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/posts/?limit=10"

# Response includes:
# {
#   "posts": [...],
#   "next_cursor": "eyJpZCI6MTIzLCJjcmVhdGVkX3RpbWUiOiIyMDI0LTAxLTE1VDEwOjMwOjAwWiJ9",
#   ...
# }

# Next page - use the cursor from previous response
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/posts/?limit=10&cursor=eyJpZCI6MTIzLCJjcmVhdGVkX3RpbWUiOiIyMDI0LTAxLTE1VDEwOjMwOjAwWiJ9"

# Continue until next_cursor is null

Benefits of cursor-based pagination: - More efficient for large datasets - Consistent results even when new posts are added during pagination - Better performance than offset-based pagination

Error Responses¶

401 Unauthorized:

{
  "detail": "Authentication required. Please provide a valid Bearer token in the Authorization header.",
  "error_code": "INVALID_CREDENTIALS",
  "status_code": 401,
  "status": "error"
}

422 Validation Error:

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "ensure this value is less than or equal to 50",
      "type": "value_error.number.not_le"
    }
  ]
}

500 Internal Server Error:

{
  "detail": "Error fetching posts: ...",
  "error_code": "INTERNAL_SERVER_ERROR",
  "status_code": 500,
  "status": "error"
}

Best Practices¶

Use platform filtering to reduce response size when you only need specific platforms
Set appropriate limits to avoid large responses (max 50 posts)
Use cursor-based pagination for large datasets (more efficient than offset-based)
Use order_by=created_time&order=desc to get the most recent posts first

Glossary - Definitions of all metrics and fields
API Reference - Complete endpoint reference
Authentication Guide - Set up authentication
Error Handling - Handle errors gracefully

Need Help?¶

Support - Contact our team