Analytics API¶

Endpoints for accessing content performance metrics and cost analytics.

Overview Analytics¶

GET /analytics

Get aggregated analytics across all missions.

Request¶

curl "https://api.amp.dev/v1/analytics?period=30d" \
  -H "Authorization: Bearer $AMP_API_KEY"

Query Parameters¶

Parameter	Type	Default	Description
`period`	string	`30d`	Time period: `7d`, `30d`, `90d`, `ytd`, `all`
`start_date`	date		Custom start date (YYYY-MM-DD)
`end_date`	date		Custom end date (YYYY-MM-DD)
`platforms`	string		Comma-separated platform filter
`granularity`	string	`day`	`hour`, `day`, `week`, `month`

Response¶

{
  "period": {
    "start": "2023-12-16",
    "end": "2024-01-15"
  },
  "summary": {
    "missions_active": 3,
    "content_published": 145,
    "total_impressions": 523400,
    "total_engagements": 18234,
    "overall_engagement_rate": 3.48,
    "total_link_clicks": 2345,
    "followers_gained": 234
  },
  "trends": {
    "impressions": {
      "current": 523400,
      "previous": 412000,
      "change_percent": 27.0,
      "direction": "up"
    },
    "engagement_rate": {
      "current": 3.48,
      "previous": 3.12,
      "change_percent": 11.5,
      "direction": "up"
    }
  },
  "by_platform": {
    "twitter": {
      "posts_published": 78,
      "impressions": 312000,
      "engagements": 11234,
      "engagement_rate": 3.60
    },
    "linkedin": {
      "posts_published": 67,
      "impressions": 211400,
      "engagements": 7000,
      "engagement_rate": 3.31
    }
  },
  "time_series": [
    {
      "date": "2024-01-01",
      "impressions": 15200,
      "engagements": 534,
      "posts": 5
    }
  ],
  "top_content": [
    {
      "content_id": "cnt_xxx",
      "platform": "twitter",
      "impressions": 12500,
      "engagement_rate": 8.2,
      "preview": "APIs shouldn't feel like puzzles..."
    }
  ]
}

Mission Analytics¶

GET /analytics/missions/:id

Get detailed analytics for a specific mission.

Request¶

curl https://api.amp.dev/v1/analytics/missions/msn_2xK9mPqR4vN8sT3w \
  -H "Authorization: Bearer $AMP_API_KEY"

Response¶

{
  "mission_id": "msn_2xK9mPqR4vN8sT3w",
  "mission_name": "Q1 Developer Outreach",
  "period": {
    "start": "2024-01-15",
    "end": "2024-01-30"
  },
  "status": "active",
  "progress_percent": 50,
  "summary": {
    "posts_published": 30,
    "posts_scheduled": 15,
    "total_impressions": 145000,
    "total_engagements": 5800,
    "engagement_rate": 4.0,
    "link_clicks": 890,
    "best_performing_day": "Tuesday",
    "best_performing_time": "14:00"
  },
  "kpi_progress": [
    {
      "metric": "engagement_rate",
      "target": 4.0,
      "current": 4.0,
      "progress_percent": 100,
      "status": "on_track",
      "projected_final": 4.2
    },
    {
      "metric": "impressions",
      "target": 100000,
      "current": 145000,
      "progress_percent": 145,
      "status": "exceeded",
      "projected_final": 290000
    }
  ],
  "content_performance": {
    "by_pillar": [
      {
        "pillar": "Thought Leadership",
        "posts": 15,
        "avg_engagement_rate": 4.5,
        "total_impressions": 82000
      },
      {
        "pillar": "Product Updates",
        "posts": 10,
        "avg_engagement_rate": 3.2,
        "total_impressions": 45000
      }
    ],
    "by_type": [
      {
        "type": "thread",
        "posts": 8,
        "avg_engagement_rate": 5.2
      },
      {
        "type": "post",
        "posts": 22,
        "avg_engagement_rate": 3.5
      }
    ]
  },
  "optimization_insights": [
    {
      "type": "timing",
      "insight": "Tuesday afternoon posts outperform by 40%",
      "confidence": 0.87
    },
    {
      "type": "content",
      "insight": "Threads with code snippets get 2.3x engagement",
      "confidence": 0.91
    }
  ]
}

Performance Metrics¶

GET /analytics/performance

Get detailed performance breakdowns.

Request¶

curl "https://api.amp.dev/v1/analytics/performance?period=30d&breakdown=platform,type" \
  -H "Authorization: Bearer $AMP_API_KEY"

Query Parameters¶

Parameter	Type	Description
`period`	string	Time period
`breakdown`	string	Dimensions: `platform`, `type`, `pillar`, `topic`, `time`
`mission_id`	string	Filter to specific mission
`sort_by`	string	Sort metric: `engagement_rate`, `impressions`, `clicks`

Response¶

{
  "period": "2023-12-16/2024-01-15",
  "breakdowns": {
    "by_platform": [
      {
        "platform": "twitter",
        "posts": 78,
        "impressions": 312000,
        "engagement_rate": 3.60,
        "clicks": 1456,
        "best_time": "14:00",
        "best_day": "Tuesday"
      },
      {
        "platform": "linkedin",
        "posts": 67,
        "impressions": 211400,
        "engagement_rate": 3.31,
        "clicks": 889,
        "best_time": "09:00",
        "best_day": "Wednesday"
      }
    ],
    "by_type": [
      {
        "type": "thread",
        "posts": 25,
        "avg_engagement_rate": 5.2,
        "avg_impressions": 8500
      },
      {
        "type": "post",
        "posts": 120,
        "avg_engagement_rate": 3.1,
        "avg_impressions": 3200
      }
    ],
    "by_time_of_day": [
      {"hour": 9, "avg_engagement_rate": 3.2, "posts": 45},
      {"hour": 12, "avg_engagement_rate": 2.8, "posts": 30},
      {"hour": 14, "avg_engagement_rate": 4.1, "posts": 50},
      {"hour": 17, "avg_engagement_rate": 3.5, "posts": 20}
    ],
    "by_day_of_week": [
      {"day": "Monday", "avg_engagement_rate": 3.0},
      {"day": "Tuesday", "avg_engagement_rate": 4.2},
      {"day": "Wednesday", "avg_engagement_rate": 3.8},
      {"day": "Thursday", "avg_engagement_rate": 3.5},
      {"day": "Friday", "avg_engagement_rate": 2.9}
    ]
  },
  "recommendations": [
    "Increase thread frequency - they outperform single posts by 68%",
    "Shift more posting to Tuesday afternoons",
    "Consider pausing Friday posts due to lower engagement"
  ]
}

Cost Analytics¶

GET /analytics/costs

Get AI generation cost breakdown.

Request¶

curl "https://api.amp.dev/v1/analytics/costs?period=30d" \
  -H "Authorization: Bearer $AMP_API_KEY"

Response¶

{
  "period": "2023-12-16/2024-01-15",
  "summary": {
    "total_cost_cents": 45600,
    "budget_limit_cents": 100000,
    "budget_used_percent": 45.6,
    "cost_per_post_cents": 314,
    "cost_per_1k_impressions_cents": 87
  },
  "by_provider": [
    {
      "provider": "claude",
      "type": "llm",
      "cost_cents": 32400,
      "requests": 1250,
      "tokens_used": 2450000
    },
    {
      "provider": "openai",
      "type": "image",
      "cost_cents": 13200,
      "images_generated": 89
    }
  ],
  "by_mission": [
    {
      "mission_id": "msn_xxx",
      "mission_name": "Q1 Developer Outreach",
      "cost_cents": 28000,
      "posts_generated": 85
    },
    {
      "mission_id": "msn_yyy",
      "mission_name": "Product Launch",
      "cost_cents": 17600,
      "posts_generated": 60
    }
  ],
  "by_stage": {
    "strategy": {"cost_cents": 5400, "percent": 11.8},
    "content": {"cost_cents": 38200, "percent": 83.8},
    "optimize": {"cost_cents": 2000, "percent": 4.4}
  },
  "time_series": [
    {"date": "2024-01-01", "cost_cents": 1520},
    {"date": "2024-01-02", "cost_cents": 1680}
  ],
  "projections": {
    "monthly_projected_cents": 68400,
    "budget_exhaustion_date": null,
    "days_until_limit": null
  }
}

Export Analytics¶

POST /analytics/export

Export analytics data to CSV or JSON.

Request¶

curl -X POST https://api.amp.dev/v1/analytics/export \
  -H "Authorization: Bearer $AMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "period": "30d",
    "include": ["content", "metrics", "costs"],
    "email_to": "user@example.com"
  }'

Parameters¶

Parameter	Type	Description
`format`	string	`csv` or `json`
`period`	string	Time period to export
`include`	array	Data types to include
`mission_ids`	array	Filter to specific missions
`email_to`	string	Email address for delivery

Response¶

{
  "export_id": "exp_xxx",
  "status": "processing",
  "estimated_completion": "2024-01-15T10:35:00Z",
  "delivery_method": "email",
  "delivery_to": "user@example.com"
}

For immediate download (small exports):

{
  "export_id": "exp_xxx",
  "status": "completed",
  "download_url": "https://api.amp.dev/v1/analytics/export/exp_xxx/download",
  "expires_at": "2024-01-16T10:30:00Z"
}

Compare Periods¶

GET /analytics/compare

Compare performance across two time periods.

Request¶

curl "https://api.amp.dev/v1/analytics/compare?period1=2024-01-01/2024-01-15&period2=2023-12-15/2023-12-31" \
  -H "Authorization: Bearer $AMP_API_KEY"

Response¶

{
  "period1": {
    "start": "2024-01-01",
    "end": "2024-01-15",
    "impressions": 245000,
    "engagement_rate": 4.2,
    "posts": 30
  },
  "period2": {
    "start": "2023-12-15",
    "end": "2023-12-31",
    "impressions": 198000,
    "engagement_rate": 3.5,
    "posts": 28
  },
  "comparison": {
    "impressions": {
      "change": 47000,
      "change_percent": 23.7,
      "direction": "up"
    },
    "engagement_rate": {
      "change": 0.7,
      "change_percent": 20.0,
      "direction": "up"
    },
    "posts": {
      "change": 2,
      "change_percent": 7.1,
      "direction": "up"
    }
  },
  "insights": [
    "Engagement rate improved 20% period-over-period",
    "Publishing volume increased slightly with better efficiency"
  ]
}

Real-time Metrics¶

GET /analytics/realtime

Get real-time metrics for recently published content.

Request¶

curl https://api.amp.dev/v1/analytics/realtime \
  -H "Authorization: Bearer $AMP_API_KEY"

Response¶

{
  "as_of": "2024-01-15T10:30:00Z",
  "last_24h": {
    "posts_published": 4,
    "impressions": 12500,
    "engagements": 456,
    "engagement_rate": 3.65
  },
  "active_content": [
    {
      "content_id": "cnt_xxx",
      "published_at": "2024-01-15T09:00:00Z",
      "platform": "twitter",
      "current_impressions": 4500,
      "current_engagements": 189,
      "velocity": "high",
      "trending": true
    }
  ],
  "next_scheduled": [
    {
      "content_id": "cnt_yyy",
      "scheduled_for": "2024-01-15T14:00:00Z",
      "platform": "linkedin"
    }
  ]
}

Errors¶

400 Bad Request¶

{
  "error": {
    "code": "invalid_period",
    "message": "Invalid period format. Use 7d, 30d, 90d, ytd, or YYYY-MM-DD/YYYY-MM-DD"
  }
}

404 Not Found¶

{
  "error": {
    "code": "not_found",
    "message": "Mission not found"
  }
}