Analytics

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

endpoint

Returns post-level analytics data including impressions, engagement, and reach.

Query Parameters

string

Filter by platform (e.g., instagram, tiktok, youtube).

string

Start date filter in ISO format (e.g., 2026-01-01).

string

End date filter in ISO format (e.g., 2026-01-31).

integer

default:"20"

Number of results per page.

integer

default:"1"

Page number for pagination.

string

Sort field. One of date or engagement.

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"

const response = await fetch(
  'https://app.nouvel.ai/api/v1/analytics?' + new URLSearchParams({
    platform: 'instagram',
    fromDate: '2026-01-01',
    limit: '10',
    sortBy: 'engagement',
    order: 'desc',
  }),
  { headers: { 'Authorization': `Bearer ${process.env.NOUVEL_API_KEY}` } }
);

const { posts, pagination, overview } = await response.json();

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

endpoint

Returns daily aggregated metrics across all posts, useful for trend analysis and reporting dashboards.

Query Parameters

string

Start of date range in ISO format.

string

End of date range in ISO format.

string

Filter by platform.

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"

const response = await fetch(
  'https://app.nouvel.ai/api/v1/analytics/daily?' + new URLSearchParams({
    startDate: '2026-01-01',
    endDate: '2026-01-31',
  }),
  { headers: { 'Authorization': `Bearer ${process.env.NOUVEL_API_KEY}` } }
);

const { data, summary } = await response.json();

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

endpoint

Returns follower growth data per connected account, with customizable time granularity.

Query Parameters

string

Start date in ISO format.

string

End date in ISO format.

string

default:"daily"

Time granularity for data points. One of daily, weekly, or monthly.

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"

const response = await fetch(
  'https://app.nouvel.ai/api/v1/analytics/followers?' + new URLSearchParams({
    fromDate: '2026-01-01',
    toDate: '2026-01-31',
    granularity: 'weekly',
  }),
  { headers: { 'Authorization': `Bearer ${process.env.NOUVEL_API_KEY}` } }
);

const { accounts, stats, dateRange } = await response.json();

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:

Code	Description
401	Invalid or missing API key
402	Plan doesn’t include API access
403	API key missing `analytics:read` permission
404	No organization found for the user
500	Internal server error

Notes

Analytics data is cached 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

Getting Started

Core Concepts

Video Generation

Projects

Publishing

AI Copilot

Analytics

Post Analytics

Query Parameters

Example

Response

Daily Metrics

Query Parameters

Example

Response

Follower Stats

Query Parameters

Example

Response

Error Codes

Notes

​Post Analytics

​Query Parameters

​Example

​Response

​Daily Metrics

​Query Parameters

​Example

​Response

​Follower Stats

​Query Parameters

​Example

​Response

​Error Codes

​Notes

Post Analytics

Query Parameters

Example

Response

Daily Metrics

Query Parameters

Example

Response

Follower Stats

Query Parameters

Example

Response

Error Codes

Notes