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
- MUST only return metrics for published posts (not drafts or scheduled)
- SHOULD calculate engagement_rate consistently: (likes + comments + shares) / impressions
- SHOULD include enough context to identify content patterns (preview, platform, timestamp)
- 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
1---2name: bolta-get-post-metrics3version: 2.0.04description: Retrieve performance metrics for published posts including likes, comments, shares, views, and engagement rate5category: analytics6roles_allowed: [Viewer, Creator, Editor, Admin]7agent_types: [analytics, content_creator, custom]8safe_defaults: {}9tools_required:10 - platform_api_integration11inputs_schema:12 type: object13 required: [account_id]14 properties:15 account_id: { type: string, description: "Social account UUID" }16 limit: { type: number, description: "Number of posts to analyze", default: 50 }17 date_from: { type: string, description: "ISO date (optional)" }18 date_to: { type: string, description: "ISO date (optional)" }19 platform: { type: string, enum: [linkedin, twitter, instagram], description: "Optional platform filter" }20outputs_schema:21 type: object22 properties:23 success: { type: boolean }24 count: { type: number }25 metrics: 26 type: array27 items:28 type: object29 properties:30 post_id: { type: string }31 content_preview: { type: string }32 published_at: { type: string }33 platform: { type: string }34 likes: { type: number }35 comments: { type: number }36 shares: { type: number }37 views: { type: number }38 impressions: { type: number }39 engagement_rate: { type: number }40organization: bolta.ai41author: Bolta Team42---4344## Goal45Retrieve 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.4647## Which Agents Use This48- **analytics** — Primary use case for performance analysis and reporting49- **content_creator** — Check what content types/topics performed best before drafting50- **custom** — Any agent needing historical performance context5152## Hard Rules531. MUST only return metrics for published posts (not drafts or scheduled)542. SHOULD calculate engagement_rate consistently: (likes + comments + shares) / impressions553. SHOULD include enough context to identify content patterns (preview, platform, timestamp)564. Require valid account_id that belongs to workspace5758## Steps5960### 1. Validate input61- Verify account_id exists and belongs to workspace62- Validate date range if provided63- Apply limit (max 100 posts per request)6465### 2. Query posts66- Fetch published posts for account_id within date range67- Filter by platform if specified68- Order by published_at desc6970### 3. Fetch platform metrics71- For each post, query platform API for performance data72- Collect: likes, comments, shares, views, impressions73- Calculate engagement_rate7475### 4. Return structured metrics76- Include post metadata (id, preview, published_at, platform)77- Include raw metrics (likes, comments, shares, views, impressions)78- Include calculated metrics (engagement_rate)7980## Output81```json82{83 "success": true,84 "count": 25,85 "metrics": [86 {87 "post_id": "uuid",88 "content_preview": "🏠 5 remote work mistakes I made...",89 "published_at": "2026-02-15T09:00:00Z",90 "platform": "linkedin",91 "likes": 47,92 "comments": 12,93 "shares": 8,94 "views": 2340,95 "impressions": 8920,96 "engagement_rate": 0.007597 }98 ]99}100```101102## Failure Handling103- If account_id not found: return error "Account not found"104- If platform API fails: return cached/stale data with warning105- If no posts found in date range: return empty array with message106107## Example Usage108109### Scenario: Analytics agent analyzing recent performance110```json111{112 "account_id": "uuid",113 "limit": 50,114 "date_from": "2026-01-01",115 "platform": "linkedin"116}117```118**Result:** Receive metrics for last 50 LinkedIn posts since Jan 1 for pattern analysis
boltaai