# GET /v1/videos/stats Returns a paginated list of tracked videos and their latest statistics for your organization. ## 📋 Overview | Property | Value | |--------------|---------------------------------------------| | **Method** | `GET` | | **Endpoint** | `https://api.influtics.com/v1/videos/stats` | | **Auth Required** | ✅ Yes | | **Credits Cost** | 🆓 Free | ## 🔐 Headers ``` Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ## 📝 Query Parameters | Parameter | Type | Required | Description | Allowed Values | |-----------|--------|----------|---------------------------------------------|---------------| | `limit` | number | No | Max number of results to return (default 50, max 100) | 1-100 | | `offset` | number | No | Number of results to skip (for pagination) | ≥0 | | `platform`| string | No | Filter by platform | tiktok, instagram, youtube, telegram, dzen, ok, vk, threads, pinterest | | `blogger_username` | string \| string[] | No | Filter videos by the creator's `channel_username`. Repeatable (`?blogger_username=a&blogger_username=b`) for UNION semantics. Empty values are dropped. Cross-platform by default — combine with `?platform=` to scope to one platform. | any string | | `status` | string | No | Filter by tracking status | active, completed, failed | | `sort` | string | No | Sort by field (default: created_at) | created_at, views, likes, updated_at | | `order` | string | No | Sort order (default: desc) | asc, desc | ### Example Request ```bash curl -X GET "https://api.influtics.com/v1/videos/stats?limit=2&platform=tiktok&status=active&sort=views&order=desc" \ -H "Authorization: Bearer your_api_key_here" ``` ## ✅ Response ```json { "success": true, "data": { "data": [ { "video_id": "77168374-dd2c-496a-b1ae-3d4944f48ccb", "external_video_id": "7489443966908189959", "stats": { "likes": { "2025-06-30 08:26:03.730104+00": 56500, "2025-06-31 08:26:03.730104+00": 56501 }, "views": { "2025-06-30 08:26:03.730104+00": 1900000, "2025-06-31 08:26:03.730104+00": 2000000 }, "reposts": { "2025-06-30 08:26:03.730104+00": 6472, "2025-06-31 08:26:03.730104+00": 6892 }, "comments": { "2025-06-30 08:26:03.730104+00": 483, "2025-06-31 08:26:03.730104+00": 526 } }, "views": 2000000, "likes": 56501, "comments": 526, "reposts": 6892, "platform": "tiktok", "created_at": "2025-06-30T08:25:29.97727+00:00", "title": "Untitled", "thumbnail_url": "https://xhrjtpcqcdqwcdiqrhfw.supabase.co/storage/v1/object/public/thumbnails/tiktok/7489443966908189959.webp", "cpm": 0, "er": 3.339736842105263, "stats_last_updated": "2025-06-30T08:26:03.730104+00:00" }, { "video_id": "44765aa4-3be2-43ee-8155-429f4def5c37", "external_video_id": "7493432998554127624", "stats": { "likes": { "2025-06-29 11:45:04.417493+00": 89700, "2025-06-30 00:01:43.584751+00": 90000 }, "views": { "2025-06-29 11:45:04.417493+00": 908200, "2025-06-30 00:01:43.584751+00": 911200 }, "reposts": { "2025-06-29 11:45:04.417493+00": 5868, "2025-06-30 00:01:43.584751+00": 5883 }, "comments": { "2025-06-29 11:45:04.417493+00": 501, "2025-06-30 00:01:43.584751+00": 502 } }, "views": 911200, "likes": 90000, "comments": 502, "reposts": 5883, "platform": "tiktok", "created_at": "2025-06-29T11:44:30.976079+00:00", "title": null, "thumbnail_url": "https://xhrjtpcqcdqwcdiqrhfw.supabase.co/storage/v1/object/public/thumbnails/tiktok/7493432998554127624.webp", "cpm": 0, "er": 10.57, "stats_last_updated": "2025-06-30T00:01:43.584751+00:00" } ], "pagination": { "total": 87, "limit": 2, "offset": 0, "has_more": true } }, "meta": { "processing_time_ms": 993, "request_id": "6bbb102e-109c-475b-b1b1-aa52ca83f060" } } ``` ## 📊 Response Fields | Field | Type | Description | |---------------------|----------|---------------------------------------------| | `video_id` | string | Internal video UUID | | `external_video_id` | string | Platform-specific video ID | | `stats` | object | Map of metric to `{timestamp: value}` objects | | `platform` | string | Platform name (e.g., tiktok, youtube) | | `created_at` | string | When the video was created (ISO 8601) | | `title` | string | Video title/caption | | `thumbnail_url` | string | Video thumbnail URL | | `cpm` | number | Cost per mille (if available) | | `payouts` | number? | Estimated creator payout. Capped at `budget`. See [Payouts](./payouts) | | `er` | number | Engagement rate (if available) | | `stats_last_updated`| string | When stats were last updated (ISO 8601) | | `views` | int? | Last views | | `likes` | int? | Last likes | | `comments` | int? | Last comments | | `reposts` | int? | Last reposts | | `deleted_at` | string? | When the video was detected as deleted (ISO 8601). `null` while healthy. Read-only. | | `deleted_reason` | object? | Why the video was detected as deleted — `{ code, message, raw }`, or `null` if no reason was recorded. Read-only. Only TikTok and VK currently report a reason. | | `meta.request_id` | string | Unique request identifier | | `meta.processing_time_ms` | number | Time taken to process the request (ms) | > **Soft-deleted videos are included in this response.** Stats are deliberately not filtered on deletion, so a deleted row still returns its last known metrics. Filter them out client-side on `deleted_at` — there is no server-side deletion filter on this endpoint. The fields are read-only and independent of `video_status`; `code` is inferred and `message` is authoritative; a `null` reason does not mean the video is healthy. Both clear to `null` when the video becomes fetchable again. Full contract: [Deletion state](./by-external-id#deletion-state). ## ⚠️ Error Responses All errors share the standard envelope `{ success: false, error: { code, message, request_id, ... } }`. The table below lists every documented `code` and the conditions that trigger it. | Status | `code` | Trigger | Additional `error` fields | |--------|--------|---------|---------------------------| | `400` | `INVALID_PARAMETER` | `sort` value is not one of `created_at`, `views`, `likes`, `updated_at`, or another required query parameter is malformed | `details.valid_sort_options: [...]` | | `401` | `INVALID_API_KEY` | The `Authorization: Bearer` API key is missing, empty, revoked, or unknown | — | ## 💡 Usage Examples ### JavaScript/Node.js ```javascript async function getVideoStats(params = {}) { const queryString = new URLSearchParams(params).toString(); const url = `https://api.influtics.com/v1/videos/stats${queryString ? '?' + queryString : ''}`; const response = await fetch(url, { headers: { 'Authorization': 'Bearer your_api_key_here', 'Content-Type': 'application/json' } }); const data = await response.json(); if (data.data) { console.log(`Found ${data.pagination.total} tracked videos`); data.data.forEach(video => { console.log(`${video.platform}: ${video.stats.views.toLocaleString()} views`); }); } } // Get top 10 TikTok videos by views getVideoStats({ platform: 'tiktok', sort: 'views', order: 'desc', limit: 10 }); ``` ### Python ```python import requests def get_video_stats(platform=None, limit=50, sort='created_at'): params = { 'limit': limit, 'sort': sort, 'order': 'desc' } if platform: params['platform'] = platform headers = { 'Authorization': 'Bearer your_api_key_here', 'Content-Type': 'application/json' } response = requests.get( 'https://api.influtics.com/v1/videos/stats', headers=headers, params=params ) if response.status_code == 200: data = response.json() print(f"Total videos: {data['pagination']['total']}") for video in data['data']: print(f"{video['platform']}: {video['stats']['views']:,} views") else: print(f"Error: {response.status_code}") # Get all Instagram videos get_video_stats(platform='instagram', sort='views') ``` ## 🎯 Use Cases - **Performance Dashboard**: Build custom analytics dashboards - **Campaign Reporting**: Generate reports for clients or stakeholders - **Growth Analysis**: Track video performance over time - **Platform Comparison**: Compare performance across different platforms - **Content Optimization**: Identify top-performing content patterns ## 📊 Filtering & Pagination ### **Get Active TikTok Videos** ```bash GET /v1/videos/stats?platform=tiktok&status=active&sort=views&order=desc ``` --- **Notes:** - If you provide an invalid value for `sort`, `order`, or `status`, you will receive a 400 error with details about allowed values. - The maximum value for `limit` is 100. - Default sort is by `created_at` in descending order. --- **Related**: [Track Video →](./track) | [View Usage →](../account/usage) :::note Missing Response Structure This documentation is based on expected functionality. Please provide the actual response structure for the `/v1/videos/stats` endpoint to ensure accuracy. :::