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
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)
brand_id	string	No	Brand identifier(s) (company_id). Can be a 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). Can be a single ID or comma-separated IDs (e.g., '4' or '4,2'). Can be used instead of brand_id. If provided, resolves to brand_id(s) automatically. Requires exactly one platform to be specified.
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
post_type	string	No	Filter posts by type(s). Use comma-separated values like 'video,image' or 'reel,carousel'. Valid values: video, image, carousel, reels, story, short, other. If empty, returns all post types.
order_by	string	No	Order posts by specified field. Valid values: interactions, revenue, reach, views, created_time. Default: created_time
order	string	No	Sort order direction. Valid values: asc, desc. Default: desc
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 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
    },
    {
      "id": 345678,
      "platform": "tiktok",
      "created_time": "2024-01-15T10:20:00Z",
      "description": "TikTok video description...",
      "title": null,
      "type": "video",
      "account_id": 3,
      "account_name": "TikTok Creator",
      "total_interactions": 1500,
      "revenue": null,
      "views": 45000,
      "duration": 30.0,
      "subjects": null,
      "category": null,
      "social_pulse": 3.2,
      "likes": 1200,
      "shares": 250,
      "average_time_watched": 18.5,
      "total_time_watched": 833250
    }
  ],
  "total_count": 3,
  "facebook_count": 1,
  "instagram_count": 1,
  "tiktok_count": 1,
  "youtube_count": 0,
  "linkedin_count": 0,
  "threads_count": 0,
  "snapchat_count": 0,
  "dailymotion_count": 0,
  "pinterest_count": 0,
  "limit_applied": 10,
  "next_cursor": "eyJpZCI6MzQ1Njc4LCJjcmVhdGVkX3RpbWUiOiIyMDI0LTAxLTE1VDEwOjIwOjAwWiJ9"
}

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 or media type of the post (platform-specific raw values). Examples: video, video_inline, photo, IMAGE, VIDEO, REELS, CAROUSEL_ALBUM, image, share, 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

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

Related Documentation

• 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