Metrics history

List the metrics history of competitors

social_competitors.snapshots.list

Lists metric snapshots, newest day first, paginated by cursor: one per platform every time the data was read (weekly, on demand, or when the screen refreshes stale data), so a day can have several. Filter by competitor_id (or __self__ for the organization's own brand), platform (instagram, facebook, youtube) and a date range (since/until, YYYY-MM-DD, inclusive). Each snapshot has followers, follows_count, total_posts, total_views, avg_likes, avg_comments, avg_views, engagement_rate (a decimal: 0.012 = 1.2%), posts_per_week, reels_share, talking_about (Facebook) and format_mix. Use it for growth over time or a benchmark between competitors. Filtering by platform without competitor_id is applied reading on until the page is full (up to 400 read per call), so a page brings fewer than limit only with has_more true at that limit: keep following next_cursor. Requires view access to Competitors. With YouTube, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their records are left out of the response (the permissions guide lists what each platform allows).

Scope

social_competitors:read

Permission

View the module

MCP tool

social_competitors_snapshots_listOn the full surface; on the compact one, mb_execute_operation with id: "social_competitors.snapshots.list".

Declared cost: up to 401 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/social-competitors/snapshots" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/social-competitors/snapshots" \
  -H "Authorization: Bearer $MB_TEST_KEY"