Analytics API¶

The Analytics API provides unified access to daily, monthly, and aggregated metrics across all supported platforms in a single endpoint.

Overview¶

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

The endpoint supports three modes: - Daily breakdown (type=daily): Returns metrics broken down by day, similar to dashboard data. Supports cursor-based pagination (max 20 results per page). - Monthly breakdown (type=monthly): Returns metrics broken down by month - Aggregated totals (type=agg): Returns aggregated metrics for the entire period, similar to leaderboard data

Get Analytics¶

GET /analytics/

Retrieve analytics data from all accessible social media platforms with daily breakdown, monthly breakdown, or aggregated totals.

Parameters¶

Parameter	Type	Required	Description
`type`	string	No	Type of analytics: `daily` for daily breakdown, `monthly` for monthly breakdown, or `agg` for aggregated totals (default: `daily`)
`since`	string	No	Start date (YYYY-MM-DD format, default: today - 7 days)
`until`	string	No	End date (YYYY-MM-DD format, default: today)
`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`	string	No	Platform codes separated by comma (e.g., `fb` or `fb,ig,sc`). If not provided, all platforms are aggregated.
`split_by_platform`	boolean	No	When `true`, results are grouped by platform only (no brand_id or account_id in response). When `false` (default), results are grouped by date, brand_id/account_id, and optionally platform.
`cursor`	string	No	Cursor for pagination (only used with `type=daily`). Use the `next_cursor` value from the previous response to get the next page. Maximum 20 results per 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`

Perimeter Rules¶

brand_id: - Optional - can be used instead of account_id or together with it - 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 - User must have access to the specified brand(s)

account_id: - Optional - can be used instead of brand_id or together with it - Can be a single ID or comma-separated IDs (e.g., 4 or 4,2) - When provided, automatically resolves to brand_id(s) for access control - account_id requires exactly one platform to be specified - Supported with type=daily, type=monthly, and type=agg - When used with type=daily, response includes account_id and account_name instead of brand_id

split_by_platform: - When split_by_platform=true: - For type=daily: Results are grouped by date and platform only (no brand_id or account_id in response) - For type=agg: Results are grouped by platform only, aggregating across all brands - Each platform will have its own aggregated metrics - Useful for comparing performance across platforms - When split_by_platform=false (default): - For type=daily: Results are grouped by date, brand_id/account_id, and optionally platform - For type=agg: Results are grouped by brand/account and optionally platform

Example Requests¶

Get daily analytics for a brand (default):

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=daily&brand_id=1&since=2025-01-15&until=2025-01-22"

Get daily analytics by platform:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=daily&brand_id=1&platform=fb&since=2025-01-15&until=2025-01-22"

Get aggregated analytics for a brand:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=agg&brand_id=1&since=2025-01-15&until=2025-01-22"

Get aggregated analytics by platform:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=agg&brand_id=1&platform=fb,ig&since=2025-01-15&until=2025-01-22"

Get analytics using account_id:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=agg&account_id=4&platform=fb&since=2025-01-15&until=2025-01-22"

Get analytics with multiple accounts:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=daily&account_id=4,2&platform=fb&since=2025-01-15&until=2025-01-22"

Get analytics grouped by platform only:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=daily&split_by_platform=true&since=2025-01-15&until=2025-01-22"

Get analytics for all accessible brands (no brand_id or account_id):

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=daily&since=2025-01-15&until=2025-01-22"

Get paginated daily analytics (first page):

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=daily&brand_id=1&since=2025-01-01&until=2025-12-31"

Get next page using cursor:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=daily&brand_id=1&since=2025-01-01&until=2025-12-31&cursor=eyJkYXRlIjoiMjAyNS0wNi0xNCIsInBsYXRmb3JtIjpudWxsfQ=="

Response Format¶

Daily Analytics Response (type=daily)¶

{
  "data": [
    {
      "date": "2025-01-22",
      "revenue": 65.00,
      "views": 322756,
      "followers": 2696849,
      "new_followers": 16,
      "posts_count": 4,
      "posts_per_day": 4.0,
      "interactions": 13597,
      "reach": 245123,
      "impressions": 322756,
      "video_views_3s": 189234,
      "views_video": 189234,
      "views_organic": 150000,
      "views_paid": 39234,
      "link_clicks": 1234,
      "engagement_rate": 0.0555,
      "interaction_rate": 0.0555,
      "likes": 8234,
      "shares": 3456,
      "comments": 1907,
      "platform": "fb",
      "brand_id": 1
    },
    {
      "date": "2025-01-21",
      "revenue": 45.12,
      "views": 298432,
      "followers": 2696833,
      "new_followers": 8,
      "posts_count": 3,
      "posts_per_day": 3.0,
      "interactions": 11234,
      "reach": 223456,
      "impressions": 298432,
      "video_views_3s": 165432,
      "views_video": 165432,
      "views_organic": 130000,
      "views_paid": 35432,
      "link_clicks": 987,
      "engagement_rate": 0.0502,
      "interaction_rate": 0.0502,
      "likes": 6789,
      "shares": 2890,
      "comments": 1555,
      "platform": "fb",
      "brand_id": 1
    }
  ],
  "total": 20,
  "since": "2025-01-15",
  "until": "2025-01-22",
  "platforms": ["fb"],
  "brand_ids": [1],
  "next_cursor": "eyJkYXRlIjoiMjAyNS0wMS0yMSIsInBsYXRmb3JtIjpudWxsfQ=="
}

Aggregated Analytics Response (type=agg)¶

{
  "data": [
    {
      "platform": "fb",
      "account_id": 4,
      "name": "Loopsider",
      "network_id": "424922021243063",
      "storage_avatar": "https://example.com/avatar.jpg",
      "permalink": "https://www.facebook.com/loopsider",
      "views": 5429041,
      "revenue": 633.00,
      "interactions": 73927,
      "posts_per_day": 5.38,
      "new_followers": 1297,
      "followers": 4573975,
      "posts_count": 43
    }
  ],
  "total": 1,
  "aggregates": {
    "total": {
      "views": 5429041,
      "revenue": 633.00,
      "interactions": 73927,
      "posts_count": 43,
      "new_followers": 1297,
      "followers": 4573975,
      "posts_per_day": 5.38
    },
    "average": {
      "views": 5429041,
      "revenue": 633.00,
      "interactions": 73927,
      "posts_per_day": 5.38,
      "new_followers": 1297,
      "followers": 4573975,
      "posts_count": 43
    }
  },
  "since": "2025-01-15",
  "until": "2025-01-22",
  "platforms": ["fb"],
  "brand_id": 1
}

Response Fields¶

Daily Analytics Fields (type=daily)¶

Core Metrics:

Field	Type	Description
`date`	string	Date in YYYY-MM-DD format
`revenue`	number	Total revenue for the day (rounded to 2 decimals)
`views`	integer	Total views
`followers`	integer	Total followers at end of day
`new_followers`	integer	New followers gained during the day
`posts_count`	integer	Number of posts published
`posts_per_day`	number	Posts per day (equals `posts_count` for daily type)
`interactions`	integer	Total interactions (likes, comments, shares, etc.).
`engagement_rate`	number	Engagement rate (interactions / reach or views, depending on platform)
`interaction_rate`	number	Interaction rate (same as engagement_rate)

Video Metrics:

Field	Type	Platform(s)	Description
`video_views_3s`	integer	Facebook	Video views (> 3 seconds)
`video_views_2s`	integer	Pinterest	Video views (> 2 seconds)
`views_video`	integer	Instagram, TikTok, YouTube, Snapchat, LinkedIn, Threads, Dailymotion	Video views (platform-specific threshold)

Reach & Impressions:

Field	Type	Platform(s)	Description
`reach`	integer	Facebook, Instagram, Snapchat, LinkedIn	Unique reach.
`impressions`	integer	Facebook, LinkedIn, Dailymotion, Pinterest	Total impressions
`ad_reach`	integer	Facebook, Instagram	Ad reach

Engagement Breakdown:

Field	Type	Platform(s)	Description
`likes`	integer	All except Snapchat	Total likes
`shares`	integer	Facebook, Instagram, TikTok, YouTube, Snapchat, LinkedIn, Threads	Total shares/reposts
`comments`	integer	Facebook, Instagram, TikTok, YouTube, LinkedIn, Threads, Pinterest	Total comments

Additional Metrics (Platform-specific):

Field	Type	Platform(s)	Description
`views_organic`	integer	Facebook, Instagram	Organic video views
`views_paid`	integer	Facebook, Instagram	Paid video views
`link_clicks`	integer	Facebook, LinkedIn	Link clicks

Metadata Fields:

Field	Type	Description
`platform`	string	Platform code (present when platform parameter is specified)
`brand_id`	integer	Brand identifier (present when multiple brands or when account_id is not used)
`account_id`	integer	Account identifier (present when account_id parameter is used)
`account_name`	string	Account name (present when account_id parameter is used)

Aggregated Analytics Fields (type=agg)¶

Core Metrics:

Field	Type	Description
`views`	integer	Total views for the period
`revenue`	number	Total revenue for the period (rounded to 2 decimals, may be `null`)
`interactions`	integer	Total interactions for the period
`posts_per_day`	number	Average number of posts per day
`new_followers`	integer	Total new followers gained during the period
`followers`	integer	Total followers at end of period
`posts_count`	integer	Total number of posts published
`engagement_rate`	number	Engagement rate
`interaction_rate`	number	Interaction rate

Video Metrics:

Field	Type	Platform(s)	Description
`video_views_3s`	integer	Facebook	Video views (> 3 seconds)
`video_views_2s`	integer	Pinterest	Video views (> 2 seconds)
`views_video`	integer	Instagram, TikTok, YouTube, Snapchat, LinkedIn, Threads, Dailymotion	Video views

Reach & Impressions:

Field	Type	Platform(s)	Description
`reach`	integer	Facebook, Instagram, Snapchat, LinkedIn	Unique reach
`impressions`	integer	Facebook, LinkedIn, Dailymotion, Pinterest	Total impressions

Engagement Breakdown:

Field	Type	Platform(s)	Description
`likes`	integer	All except Snapchat	Total likes
`shares`	integer	Facebook, Instagram, TikTok, YouTube, Snapchat, LinkedIn, Threads	Total shares
`comments`	integer	Facebook, Instagram, TikTok, YouTube, LinkedIn, Threads, Pinterest	Total comments

Additional Metrics (Platform-specific):

Field	Type	Platform(s)	Description
`views_organic`	integer	Facebook, Instagram	Organic video views
`views_paid`	integer	Facebook, Instagram	Paid video views
`link_clicks`	integer	Facebook, LinkedIn	Link clicks

Account Metadata:

Field	Type	Description
`name`	string	Account name
`network_id`	string	Platform-specific network/channel ID
`storage_avatar`	string	URL to account avatar image
`permalink`	string	URL to account profile/page
`platform`	string	Platform code (present when platform parameter is specified)
`account_id`	integer	Account identifier

Response Metadata¶

Field	Type	Description
`data`	array	Array of analytics data entries
`total`	integer	Total number of entries returned in current page
`since`	string	Start date of the query period
`until`	string	End date of the query period
`platforms`	string \| array	Platform(s) included in the query
`brand_id`	integer	Brand identifier (present when single brand_id is used)
`brand_ids`	array	Array of brand identifiers
`next_cursor`	string	Cursor for pagination (present only in `type=daily` responses when there are more results)

Platform Behavior¶

Without platform parameter: - Data is summed across all platforms - Single aggregated result per date/brand/account

With platform parameter: - Data is broken down by specified platforms - Separate entries for each platform - Platform code included in response

With split_by_platform=true: - Results are grouped by platform only - No brand_id or account_id in response - Useful for comparing performance across platforms - When used with type=daily and pagination, each platform counts as a separate entry

Pagination (type=daily only)¶

The type=daily endpoint supports cursor-based pagination to efficiently handle large date ranges:

Maximum 20 results per page - Each page contains at most 20 entries
Cursor-based - Use the cursor parameter with the next_cursor value from the previous response
Optimized queries - The API automatically optimizes date ranges based on the cursor to reduce database load
split_by_platform support - When split_by_platform=true, pagination accounts for multiple entries per date (one per platform)

How it works: 1. Make your first request without a cursor parameter 2. If the response includes a next_cursor field, there are more results available 3. Use the next_cursor value as the cursor parameter in your next request 4. Repeat until next_cursor is null or absent

Example pagination flow:

# First request
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=daily&brand_id=1&since=2025-01-01&until=2025-12-31"

# Response includes next_cursor
# {
#   "data": [...],
#   "next_cursor": "eyJkYXRlIjoiMjAyNS0wNi0xNCIsInBsYXRmb3JtIjpudWxsfQ=="
# }

# Second request (next page)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=daily&brand_id=1&since=2025-01-01&until=2025-12-31&cursor=eyJkYXRlIjoiMjAyNS0wNi0xNCIsInBsYXRmb3JtIjpudWxsfQ=="

Important notes: - The cursor parameter is only used with type=daily - The since and until parameters should remain the same across pagination requests - When split_by_platform=true, the cursor includes platform information to handle multiple entries per date correctly

Error Responses¶

400 Bad Request:

{
  "detail": "account_id requires exactly one platform to be specified"
}

401 Unauthorized:

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

403 Forbidden:

{
  "detail": "User doesn't have access to the specified brand_id(s)",
  "error_code": "FORBIDDEN",
  "status_code": 403,
  "status": "error"
}

404 Not Found:

{
  "detail": "account_id not found or doesn't belong to any accessible brand",
  "error_code": "NOT_FOUND",
  "status_code": 404,
  "status": "error"
}

422 Validation Error:

{
  "detail": [
    {
      "loc": ["query", "type"],
      "msg": "string does not match regex '^(daily|agg|monthly)$'",
      "type": "value_error.str.regex"
    }
  ]
}

500 Internal Server Error:

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