Live Data

List Account Videos

Fetches an account's most recent videos, newest first.

PlatformplatformAccountIdPagesNotes
TikTokaccount idpaged
Instagramaccount idpaged, 12 a pageReels the account posted itself, collabs included
YouTubechannel idpaged, 48 a pageShorts. The channel's 15 newest have their exact view count, like count and publish date; the others an id, title, thumbnail and a rounded view count
Facebookaccount id or handlepagedReels
Snapchatthe handleone page of about 29the platform_account_id this API returns for Snapchat is not accepted here

A page is as long as the platform makes it. There is no page-size parameter: a limit in the query is ignored, and more videos come from the next pageToken.

Examples:

  • GET /live/tiktok/accounts/208464585232822272/videos
  • GET /live/tiktok/accounts/208464585232822272/videos?pageToken=... with the nextPageToken of the page before
  • GET /live/snapchat/accounts/nike/videos

Fields a platform does not publish are null. region is a hint: TikTok uses it as the country the lookup is made from, the other platforms ignore it. A pageToken on a platform that has one page returns an empty page and is not charged.

Optional live endpoint. You do not need this endpoint for normal API integrations; prefer tracked accounts, tracked videos, analytics, projects, and Creator Hub endpoints when working with viral.app data.

⚠️ Consumes extra credits: 3 credits per request. Additional charges may apply.

Headers:

  • X-Viral-Credits-Consumed
  • X-Viral-Credits-Meter
  • X-Viral-Credits-Benefited-Remaining
  • X-Viral-Credits-Can-Purchase-Extra
  • Retry-After (on 429 responses)

A page past the only one of a one-page lookup costs nothing: it carries X-Viral-Credits-Consumed: 0 and X-Viral-Credits-Meter, without the two balance headers.

get/live/{platform}/accounts/{platformAccountId}/videos

Request

  • Base URL: https://viral.app/api/v1
  • URL: https://viral.app/api/v1/live/{platform}/accounts/{platformAccountId}/videos
  • Auth: API key in header x-api-key

Path parameters

platform'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat' required

Social media platform (facebook, instagram, tiktok, youtube, snapchat)

Example:facebook
platformAccountIdstring required

Native platform account id

Example:7123456789012345678

Query parameters

pageTokenstring nullable

Opaque cursor token used to fetch the next page

Example:v2:eyJvZmZzZXQiOjIwLCJsaW1pdCI6MjB9
regionstring nullable

Region code (2-letter ISO country code)

Example:US

Response

OK

nextPageTokenstring nullable required

Example response

{
  "videos": [
    {
      "platform": "facebook",
      "platform_video_id": "7123456789012345678",
      "platform_account_id": "7123456789012345678",
      "account_profile_picture_url": "https://www.myproject.com",
      "region": "US",
      "hashtags": [
        "brand"
      ],
      "thumbnail_url": "https://www.myproject.com",
      "download_url": "https://www.myproject.com",
      "music_play_url": "https://www.myproject.com",
      "image_urls": [
        "https://www.myproject.com"
      ],
      "music_cover_url": "https://www.myproject.com"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.