Skip to main content
The Analytics API provides three endpoints for tracking social media performance across all connected accounts. All analytics endpoints require the analytics:read permission.
Analytics data is cached and refreshed at most once per hour. Recent posts may take up to 60 minutes to appear in analytics results.

​
Post Analytics

​
GET /api/v1/analytics
endpoint
Returns post-level analytics data including impressions, engagement, and reach.

​
Query Parameters

​
platform
string
Filter by platform (e.g., instagram, tiktok, youtube).
​
fromDate
string
Start date filter in ISO format (e.g., 2026-01-01).
​
toDate
string
End date filter in ISO format (e.g., 2026-01-31).
​
limit
integer
default:"20"
Number of results per page.
​
page
integer
default:"1"
Page number for pagination.
​
sortBy
string
Sort field. One of date or engagement.
​
order
string
Sort direction. One of asc or desc.

​
Example

curl "https://app.nouvel.ai/api/v1/analytics?platform=instagram&fromDate=2026-01-01&limit=10&sortBy=engagement&order=desc" \
  -H "Authorization: Bearer nvl_xxxx"

​
Response

{
  "posts": [
    {
      "_id": "post_id",
      "content": "Post caption text...",
      "publishedAt": "2026-01-15T12:00:00Z",
      "platform": "instagram",
      "analytics": {
        "impressions": 5000,
        "reach": 3200,
        "likes": 450,
        "comments": 32,
        "shares": 15,
        "saves": 89,
        "clicks": 120,
        "views": 4800,
        "engagementRate": 0.092
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 45
  },
  "overview": {
    "totalImpressions": 125000,
    "totalEngagement": 8500,
    "avgEngagementRate": 0.068
  }
}

​
Daily Metrics

​
GET /api/v1/analytics/daily
endpoint
Returns daily aggregated metrics across all posts, useful for trend analysis and reporting dashboards.

​
Query Parameters

​
startDate
string
Start of date range in ISO format.
​
endDate
string
End of date range in ISO format.
​
platform
string
Filter by platform.
​
accountId
string
Filter by specific account ID (from GET /api/v1/accounts).

​
Example

curl "https://app.nouvel.ai/api/v1/analytics/daily?startDate=2026-01-01&endDate=2026-01-31&platform=instagram" \
  -H "Authorization: Bearer nvl_xxxx"

​
Response

{
  "data": [
    {
      "date": "2026-01-15",
      "postCount": 3,
      "metrics": {
        "impressions": 12000,
        "reach": 8500,
        "likes": 890,
        "comments": 45,
        "shares": 23,
        "saves": 156,
        "clicks": 340,
        "views": 11000
      }
    },
    {
      "date": "2026-01-16",
      "postCount": 1,
      "metrics": {
        "impressions": 4500,
        "reach": 3100,
        "likes": 320,
        "comments": 18,
        "shares": 9,
        "saves": 67,
        "clicks": 145,
        "views": 4200
      }
    }
  ],
  "summary": {
    "totalPosts": 4,
    "totalImpressions": 16500,
    "avgDailyEngagement": 765
  }
}

​
Follower Stats

​
GET /api/v1/analytics/followers
endpoint
Returns follower growth data per connected account, with customizable time granularity.

​
Query Parameters

​
fromDate
string
Start date in ISO format.
​
toDate
string
End date in ISO format.
​
granularity
string
default:"daily"
Time granularity for data points. One of daily, weekly, or monthly.
​
accountIds
string
Comma-separated list of account IDs to filter by (from GET /api/v1/accounts).

​
Example

curl "https://app.nouvel.ai/api/v1/analytics/followers?fromDate=2026-01-01&toDate=2026-01-31&granularity=weekly" \
  -H "Authorization: Bearer nvl_xxxx"

​
Response

{
  "accounts": [
    {
      "_id": "6612f1a2b3c4d5e6f7890123",
      "platform": "instagram",
      "username": "mybrand",
      "currentFollowers": 15000,
      "growth": 1200,
      "growthPercentage": 8.7
    }
  ],
  "stats": {
    "6612f1a2b3c4d5e6f7890123": [
      { "date": "2026-01-01", "followers": 13800 },
      { "date": "2026-01-08", "followers": 14200 },
      { "date": "2026-01-15", "followers": 14600 },
      { "date": "2026-01-22", "followers": 15000 }
    ]
  },
  "dateRange": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  }
}

​
Error Codes

All analytics endpoints share the same error codes:
CodeDescription
401Invalid or missing API key
402Plan doesn’t include API access
403API key missing analytics:read permission
404No organization found for the user
500Internal server error

​
Notes

  • All three analytics endpoints proxy to the underlying analytics provider (Late.dev)
  • Data is cached on the provider side and refreshed at most once per hour
  • The overview and summary fields contain aggregated totals across the query scope
  • Available metrics vary by platform — not all platforms report all metric types