Bolta.get Post Metrics

Goal

Retrieve performance metrics for published posts to identify patterns and make data-driven content recommendations. Analytics agents use this to understand what works and what doesn't.

Which Agents Use This

• analytics — Primary use case for performance analysis and reporting
• content_creator — Check what content types/topics performed best before drafting
• custom — Any agent needing historical performance context

Hard Rules

1. MUST only return metrics for published posts (not drafts or scheduled)
2. SHOULD calculate engagement_rate consistently: (likes + comments + shares) / impressions
3. SHOULD include enough context to identify content patterns (preview, platform, timestamp)
4. Require valid account_id that belongs to workspace

Steps

1. Validate input

• Verify account_id exists and belongs to workspace
• Validate date range if provided
• Apply limit (max 100 posts per request)

2. Query posts

• Fetch published posts for account_id within date range
• Filter by platform if specified
• Order by published_at desc

3. Fetch platform metrics

• For each post, query platform API for performance data
• Collect: likes, comments, shares, views, impressions
• Calculate engagement_rate

4. Return structured metrics

• Include post metadata (id, preview, published_at, platform)
• Include raw metrics (likes, comments, shares, views, impressions)
• Include calculated metrics (engagement_rate)

Output

{
  "success": true,
  "count": 25,
  "metrics": [
    {
      "post_id": "uuid",
      "content_preview": "🏠 5 remote work mistakes I made...",
      "published_at": "2026-02-15T09:00:00Z",
      "platform": "linkedin",
      "likes": 47,
      "comments": 12,
      "shares": 8,
      "views": 2340,
      "impressions": 8920,
      "engagement_rate": 0.0075
    }
  ]
}

Failure Handling

• If account_id not found: return error "Account not found"
• If platform API fails: return cached/stale data with warning
• If no posts found in date range: return empty array with message

Example Usage

Scenario: Analytics agent analyzing recent performance

{
  "account_id": "uuid",
  "limit": 50,
  "date_from": "2026-01-01",
  "platform": "linkedin"
}

Result: Receive metrics for last 50 LinkedIn posts since Jan 1 for pattern analysis