> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nouvel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Track post performance, daily metrics, and follower growth across platforms

The Analytics API provides three endpoints for tracking social media performance across all connected accounts. All analytics endpoints require the `analytics:read` permission.

<Note>
  Analytics data is cached and refreshed at most once per hour. Recent posts may take up to 60 minutes to appear in analytics results.
</Note>

***

## Post Analytics

<ParamField path="GET /api/v1/analytics" type="endpoint">
  Returns post-level analytics data including impressions, engagement, and reach.
</ParamField>

### Query Parameters

<ParamField query="platform" type="string">
  Filter by platform (e.g., `instagram`, `tiktok`, `youtube`).
</ParamField>

<ParamField query="fromDate" type="string">
  Start date filter in ISO format (e.g., `2026-01-01`).
</ParamField>

<ParamField query="toDate" type="string">
  End date filter in ISO format (e.g., `2026-01-31`).
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of results per page.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="sortBy" type="string">
  Sort field. One of `date` or `engagement`.
</ParamField>

<ParamField query="order" type="string">
  Sort direction. One of `asc` or `desc`.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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

<ParamField path="GET /api/v1/analytics/daily" type="endpoint">
  Returns daily aggregated metrics across all posts, useful for trend analysis and reporting dashboards.
</ParamField>

### Query Parameters

<ParamField query="startDate" type="string">
  Start of date range in ISO format.
</ParamField>

<ParamField query="endDate" type="string">
  End of date range in ISO format.
</ParamField>

<ParamField query="platform" type="string">
  Filter by platform.
</ParamField>

<ParamField query="accountId" type="string">
  Filter by specific account ID (from [GET /api/v1/accounts](/api-reference/accounts)).
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://app.nouvel.ai/api/v1/analytics/daily?startDate=2026-01-01&endDate=2026-01-31&platform=instagram" \
    -H "Authorization: Bearer nvl_xxxx"
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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

<ParamField path="GET /api/v1/analytics/followers" type="endpoint">
  Returns follower growth data per connected account, with customizable time granularity.
</ParamField>

### Query Parameters

<ParamField query="fromDate" type="string">
  Start date in ISO format.
</ParamField>

<ParamField query="toDate" type="string">
  End date in ISO format.
</ParamField>

<ParamField query="granularity" type="string" default="daily">
  Time granularity for data points. One of `daily`, `weekly`, or `monthly`.
</ParamField>

<ParamField query="accountIds" type="string">
  Comma-separated list of account IDs to filter by (from [GET /api/v1/accounts](/api-reference/accounts)).
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://app.nouvel.ai/api/v1/analytics/followers?fromDate=2026-01-01&toDate=2026-01-31&granularity=weekly" \
    -H "Authorization: Bearer nvl_xxxx"
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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