UGC.runLegacy reporting
Top-performing videos
Retrieve your most-viewed videos across three reporting windows.
GET
/api/metrics/top-videosRequest
No query parameters are required. Each list contains at most four videos, sorted by stored view count, highest first. Videos marked as disqualified are excluded.
bash
curl "https://www.ugc.run/api/metrics/top-videos" \
--header "Authorization: Bearer $UGC_API_KEY"Reporting windows
Windows filter by publication time. Views and engagement are the stored lifetime totals for each video, not changes during the window. The lists overlap, so the same video may appear in more than one list.
| Field | Window |
|---|---|
| recent | Today and the preceding 24 hours, anchored to midnight in the project time zone. |
| week | Today and the preceding six 24-hour periods. |
| month | Today and the preceding 29 24-hour periods. |
Response
This example shows the video shape in recent. The week and month lists are omitted here for brevity; in a complete response, they may contain the same video and other qualifying posts.
json · illustrative
{
"project": "studio",
"timezone": "America/Los_Angeles",
"recent": [
{
"id": "video_example",
"platform": "instagram",
"description": "A day in the studio",
"views": 24000,
"likes": 1200,
"comments": 48,
"shares": 92,
"thumbnailUrl": "https://example.com/thumbnail.jpg",
"permalink": "https://www.instagram.com/reel/example/",
"publishedAt": "2026-09-07T16:30:00Z",
"creatorName": "Alex"
}
]
}Video fields
| Field | Type | Description |
|---|---|---|
| id | string | Video identifier. |
| platform | string | Social platform, such as instagram or tiktok. |
| description | string | null | Stored caption. |
| views / likes / comments / shares | number | Stored engagement counts. |
| thumbnailUrl | string | null | Thumbnail URL; availability may change. |
| permalink | string | null | Original social post URL. |
| publishedAt | string | Publication timestamp in ISO 8601 format. |
| creatorName | string | null | Name of the associated creator. |