Analytics API¶

The Analytics API provides unified access to both daily 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 two modes: - Daily breakdown (type=daily): Returns metrics broken down by day, similar to dashboard data - 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 or aggregated totals.

Parameters¶

Parameter	Type	Required	Description
`type`	string	No	Type of analytics: `daily` for daily breakdown or `agg` for aggregated totals (default: `daily`)
`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	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`. If not provided, data is summed across all platforms.
`since`	string	No	Start date (YYYY-MM-DD format, default: today - 7 days)
`until`	string	No	End date (YYYY-MM-DD format, default: today)
`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.

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 both type=daily 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"

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,
      "interactions": 13597,
      "platform": "fb",
      "brand_id": 1
    },
    {
      "date": "2025-01-21",
      "revenue": 45.12,
      "views": 298432,
      "followers": 2696833,
      "new_followers": 8,
      "posts_count": 3,
      "interactions": 11234,
      "platform": "fb",
      "brand_id": 1
    }
  ],
  "total": 8,
  "since": "2025-01-15",
  "until": "2025-01-22",
  "platforms": ["fb"],
  "brand_id": 1
}

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,
      "views_video": 5192335,
      "revenue": 633.00,
      "interactions": 73927,
      "posts_per_day": 5.38,
      "new_followers": 1297,
      "followers": 4573975,
      "posts_count": 43
    }
  ],
  "total": 1,
  "aggregates": {
    "total": {
      "views": 5429041,
      "views_video": 5192335,
      "revenue": 633.00,
      "interactions": 73927,
      "posts_count": 43
    },
    "average": {
      "views": 5429041,
      "views_video": 5192335,
      "revenue": 633.00,
      "interactions": 73927,
      "posts_per_day": 5.38
    }
  },
  "since": "2025-01-15",
  "until": "2025-01-22",
  "platforms": ["fb"],
  "brand_id": 1
}

Response Fields¶

Daily Analytics Fields (type=daily)¶

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
`interactions`	integer	Total interactions (likes, comments, shares, etc.)
`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)¶

Field	Type	Description
`views`	integer	Total views for the period
`views_video`	integer	Total video 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
`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
`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 (`"all"` or array of platform codes)
`brand_id`	integer	Brand identifier (present when single brand_id is used)
`brand_ids`	array	Array of brand identifiers (present when multiple brand_ids are used)
`aggregates`	object	Aggregated totals and averages (present only in `type=agg` responses)

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

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)$'",
      "type": "value_error.str.regex"
    }
  ]
}

500 Internal Server Error:

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

Best Practices¶

Use appropriate type parameter - Use type=daily for time-series analysis and type=agg for summary statistics
Filter by platform - Use the platform parameter to reduce response size when you only need specific platforms
Use date ranges wisely - Keep date ranges reasonable (7-30 days) for better performance
Use split_by_platform - Set split_by_platform=true when comparing performance across platforms
Use account_id for account-level data - Use account_id instead of brand_id when you need account-specific metrics
Handle multiple brands - When querying multiple brands, results are automatically grouped by brand_id

API Reference - Complete endpoint reference
Endpoint Fields Reference - Detailed field descriptions
Authentication Guide - Set up authentication
Error Handling - Handle errors gracefully

Need Help?¶

Support - Contact our team