The Analytics API provides three complementary endpoints for retrieving performance data. Choose the right endpoint based on your use case.

Quick Reference

Endpoint	Purpose	Use When	Response
`/analytics/summary`	High-level overview	Building dashboards, quick status checks	Aggregated metrics by platform
`/analytics/unified`	Detailed row-level data	Analyzing post performance, detailed reports	Per-post metrics as rows
`/analytics/insights`	AI-generated insights	Making data-driven decisions	Actionable recommendations

Summary Endpoint

GET /api/public/v1/analytics/summary

Returns aggregated performance metrics across all platforms.

curl "$AIDELLY_API_BASE/analytics/summary?timeframe=last_30_days" \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID"

Query Parameters:

timeframe — last_7_days, last_30_days, last_90_days, all_time (default: last_30_days)
startDate — custom start date (ISO 8601, overrides timeframe)
endDate — custom end date (ISO 8601, overrides timeframe)
includeInsights — set to true to include AI insights (default: false)
includeActivity — set to true to include activity timeline (default: false)

Response:

{
  "success": true,
  "data": {
    "total_posts": 127,
    "total_engagements": 3421,
    "average_engagement_rate": 0.027,
    "by_platform": {
      "linkedin": {
        "posts": 45,
        "engagements": 1820,
        "engagement_rate": 0.0404,
        "impressions": 45000,
        "clicks": 890
      },
      "twitter": {
        "posts": 52,
        "engagements": 1210,
        "engagement_rate": 0.0233,
        "impressions": 52000,
        "retweets": 340
      },
      "facebook": {
        "posts": 30,
        "engagements": 391,
        "engagement_rate": 0.013,
        "impressions": 30000,
        "reactions": 280
      }
    },
    "insights": [],
    "recent_activity": null
  },
  "request_id": "uuid"
}

Use for:

Dashboard KPI cards
Trend monitoring
Quick health checks
Email reports

Unified Endpoint

GET /api/public/v1/analytics/unified

Returns detailed, row-level performance data for each post.

curl "$AIDELLY_API_BASE/analytics/unified?from=2026-02-01T00:00:00Z&to=2026-02-28T23:59:59Z" \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID"

Query Parameters:

from — start date (ISO 8601, required)
to — end date (ISO 8601, required)
platforms — filter by platforms (comma-separated: linkedin,twitter,facebook)

Response:

{
  "success": true,
  "data": {
    "rows": [
      {
        "post_id": "post_uuid",
        "platform": "linkedin",
        "content_text": "Check out our latest update...",
        "published_at": "2026-02-15T14:30:00Z",
        "impressions": 2500,
        "engagements": 145,
        "engagement_rate": 0.058,
        "clicks": 42,
        "comments": 18,
        "shares": 12,
        "reactions": 115,
        "reach": 2200,
        "save_count": 8
      },
      {
        "post_id": "post_uuid_2",
        "platform": "twitter",
        "content_text": "New feature announcement...",
        "published_at": "2026-02-14T09:00:00Z",
        "impressions": 1800,
        "engagements": 92,
        "engagement_rate": 0.051,
        "retweets": 34,
        "replies": 28,
        "likes": 30,
        "bookmarks": 5
      }
    ],
    "count": 2
  },
  "request_id": "uuid"
}

Use for:

Detailed post performance analysis
Comparative analysis (which post performed best?)
Exporting data to external tools
Building custom reports
Platform-specific insights

Insights Endpoint

GET /api/public/v1/analytics/insights

Returns AI-generated insights and recommendations based on your performance data.

curl "$AIDELLY_API_BASE/analytics/insights?limit=5&type=performance" \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID"

Query Parameters:

limit — max insights to return (default: 5, max: 20)
type — filter by insight type (performance, timing, content, growth)
platforms — filter by platforms (comma-separated)
dismissed — filter by dismissed status (true, false)

Response:

{
  "success": true,
  "data": [
    {
      "id": "insight_uuid",
      "insight_type": "performance",
      "title": "LinkedIn performing 3x better than Twitter",
      "description": "Your recent posts on LinkedIn have 3x higher engagement rates compared to Twitter. Consider increasing LinkedIn posting frequency.",
      "impact": "high",
      "confidence": 0.92,
      "actionable": true,
      "suggested_actions": [
        "Increase LinkedIn posting frequency to 2x per week",
        "Tailor content specifically for LinkedIn audience",
        "Test longer-form content on LinkedIn"
      ],
      "related_metrics": {
        "linkedin_avg_engagement": 0.058,
        "twitter_avg_engagement": 0.019
      },
      "platforms": ["linkedin", "twitter"],
      "created_at": "2026-02-18T10:30:00Z",
      "dismissed": false
    },
    {
      "id": "insight_uuid_2",
      "insight_type": "timing",
      "title": "Peak engagement window: 9-11 AM on weekdays",
      "description": "Posts published between 9-11 AM on weekdays receive 45% higher engagement. Concentrate your posting around this window.",
      "impact": "medium",
      "confidence": 0.87,
      "actionable": true,
      "suggested_actions": [
        "Schedule posts for 9-11 AM on weekdays",
        "Test this timing consistently for 2 weeks",
        "Track engagement rate changes"
      ],
      "related_metrics": {
        "peak_window_engagement": 0.065,
        "overall_avg_engagement": 0.045
      },
      "platforms": ["linkedin", "twitter"],
      "created_at": "2026-02-17T14:00:00Z",
      "dismissed": false
    }
  ],
  "request_id": "uuid"
}

Choosing an Endpoint

Use Summary if:

You need a quick overview
Building a dashboard
Tracking top-level metrics (total posts, average engagement)
You want to include AI insights in a summary view

Use Unified if:

Analyzing individual post performance
Comparing posts side-by-side
Exporting data for external analysis
Building detailed performance reports
You need row-level filtering or sorting

Use Insights if:

Seeking actionable recommendations
Making strategic posting decisions
Identifying trends and patterns
You want AI-driven guidance

Combining Endpoints

For a comprehensive analytics workflow:

# Step 1: Get summary to identify trends
SUMMARY=$(curl -s "$AIDELLY_API_BASE/analytics/summary" \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID")

# Step 2: If summary looks good, get insights
INSIGHTS=$(curl -s "$AIDELLY_API_BASE/analytics/insights" \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID")

# Step 3: For detailed analysis, fetch unified data
UNIFIED=$(curl -s "$AIDELLY_API_BASE/analytics/unified?from=2026-02-01T00:00:00Z&to=2026-02-28T23:59:59Z" \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID")

Error Handling

Common analytics errors:

Code	Status	Meaning
`PUBLIC_API_ANALYTICS_SUMMARY_FAILED`	500	Unable to calculate summary metrics
`PUBLIC_API_ANALYTICS_UNIFIED_FAILED`	500	Unable to fetch unified data
`PUBLIC_API_QUERY_INVALID`	400	Invalid query parameters (date format, platform names, etc.)

Rate Limits

Analytics endpoints count toward your plan's read rate limit. See Rate Limits for details by plan.

Analytics Endpoints