Video Analytics

Export videos to CSV

Exports filtered videos data as CSV file stored in R2. Returns a presigned download URL valid for 5 minutes.

post/videos/export

Request

  • Base URL: https://viral.app/api/v1
  • URL: https://viral.app/api/v1/videos/export
  • Auth: API key in header x-api-key

Request body

platformsstring[] nullable

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

accountUsernamestring

Account username on the platform

accountsstring[] nullable

Organization account IDs

contentTypesstring[] nullable

Content types (video, slideshow)

projectsstring[] nullable

Organization project IDs

tagsstring[] nullable

Tag IDs. Custom and project tags must all match (intersection); country tags and continent:<CODE> values combine into one geographic group satisfied by any of them. none:<category> values (custom/project/country/continent) match entities WITHOUT any tag of the category. Ignored when tagGroups is provided.

expandstring[]

Expand related resources in the response

viewMode'internal' | 'competitors' | 'all'
visibility'visible' | 'excluded'

Exclusion-state filter: "visible" (default) hides excluded videos, "excluded" returns only excluded videos

Example request

{
  "platforms": [
    "tiktok",
    "instagram"
  ],
  "accountUsername": "viral_creator",
  "accounts": null,
  "dateRange": {
    "from": "2025-01-01",
    "to": "2025-01-31"
  },
  "contentTypes": [
    "video"
  ]
}

Response

OK

downloadUrlstring uri required

Presigned download URL for the CSV export file

expiresAtstring date-time required

Expiration timestamp for the download URL (typically 5 minutes)

rowCountnumber required

Total number of data rows included in the export file

fileNamestring required

Generated filename for the export (includes timestamp)

Example response

{
  "downloadUrl": "https://storage.cloudflare.com/exports/video-daily-gains-2025-12-20-143052.csv?signature=abc123",
  "expiresAt": "2025-12-20T14:35:52.000Z",
  "rowCount": 15420,
  "fileName": "video-daily-gains-2025-12-20-143052.csv"
}

Changes

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