Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev.magicpost.in/llms.txt

Use this file to discover all available pages before exploring further.

The metrics endpoints give you access to your LinkedIn analytics data stored in MagicPost. Use GET /metrics/summary for a compact KPI snapshot, and POST /refresh-posts when you need to pull the latest data directly from LinkedIn before querying.

​
GET /api/v1/metrics/summary

Returns aggregated analytics for a given time period, including totals, per-post averages, and your top-performing posts by impressions. Query parameters
ParameterTypeDefaultDescription
periodstring30dTime window: 7d, 30d, 90d, 180d, or all.
top_ninteger5Number of top posts to return. Clamped to 1–20.
curl "https://api.magicpost.in/api/v1/metrics/summary?period=30d&top_n=5" \
  -H "Authorization: Bearer mp_xxx"
Response 
{
  "period": "30d",
  "profile": {
    "name": "Naïlé Titah",
    "headline": "CEO @MagicPost",
    "followers_total": 24174
  },
  "access": {
    "linkedin_connected": true,
    "impressions_access": true
  },
  "totals": {
    "posts_count": 10,
    "impressions": 56147,
    "likes": 740,
    "comments": 319,
    "reposts": 11
  },
  "averages_per_post": {
    "impressions": 5614.7,
    "likes": 74.0,
    "comments": 31.9,
    "reposts": 1.1
  },
  "top_posts": [
    {
      "urn": "urn:li:share:...",
      "post_url": "https://linkedin.com/feed/update/urn:li:...",
      "posted_at": "2026-05-12T07:30:00Z",
      "text_preview": "First 200 chars of the post...",
      "num_impressions": 12500,
      "num_likes": 180,
      "num_comments": 45,
      "num_reposts": 3
    }
  ]
}
access.impressions_access will be false if your LinkedIn account hasn’t granted MagicPost analytics permissions. In that case, impression counts will be null.

​
POST /api/v1/refresh-posts

Triggers an asynchronous pull of your latest LinkedIn post data. Use this before querying GET /metrics/summary when you need up-to-date analytics.
This endpoint is rate-limited to 5 requests per minute per token, because each call makes outbound requests to the LinkedIn API.
curl -X POST https://api.magicpost.in/api/v1/refresh-posts \
  -H "Authorization: Bearer mp_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'
Response 
{ "success": true, "job_id": "uuid", "status": "pending" }
The sync runs asynchronously. Use the returned job_id to poll GET /api/v1/refresh-posts/<job_id> until status reaches a terminal state.

​
GET /api/v1/refresh-posts/<job_id>

Poll the status of a refresh job started by POST /api/v1/refresh-posts. 
curl https://api.magicpost.in/api/v1/refresh-posts/uuid \
  -H "Authorization: Bearer mp_xxx"
Response 
{
  "job_id": "uuid",
  "processed": 50,
  "total": 50,
  "status": "finished",
  "error": null
}
Status values
ValueDescription
pendingJob queued, not yet started.
runningActively pulling data from LinkedIn.
finishedCompleted successfully.
successAlias for finished in some responses.
errorJob failed. Check the error field for details.
Returns 404 if the job ID doesn’t exist or was started by a different user.