Videos

Videos are the content units within a bundle. Each video occupies a specific position (1-indexed) in the bundle and represents a single piece of content to be published on a creator's social media account.

Video Types

Every video has a video_type that determines what content it contains:

Platform-Specific Behavior

Each platform supports different combinations of video types and has its own requirements.

TikTok

Instagram

Instagram requires the instagram_content_type field to distinguish between reels and feed posts:

INFO: Reel Fixed Photos vs Post Carousel On Instagram, video_type: "carousel" behaves differently depending on instagram_content_type:

• With "reel": Instagram creates a video from your images (Fixed Photos — not swipeable). This is a Reel, not a carousel.
• With "post": Instagram creates a swipeable photo carousel in the feed.

Instagram also supports video_type: "story" (one video or one image, no instagram_content_type). See Configure Videos → Story Fields.

YouTube

YouTube accounts cannot be ordered through the API. Public bundle creation supports TikTok and Instagram only, and a YouTube bundle is rejected with YOUTUBE_DELAYED — even though GET /credit-costs lists a YouTube price, the price is real but the order path is not open. YouTube accounts are delivered through a separate, non-API flow; talk to the team. You may still see reserved YouTube fields in templates and generated schemas.

Video Status Lifecycle

Each video progresses through the following statuses:

pending → configured → published → accepted → in_review → finalized

The 72-hour window starts when the video listing enters in_review. Finalize it to approve it immediately, or request corrections before the window expires. If neither action is taken, finalization is automatic — this applies regardless of auto_finalize_videos, which does not switch automatic finalization off.

Platform Signals

Once a video is live, TokPortal checks what the platform did with it: about 48 hours after posting and again after 7 days, plus whenever the post is scraped for analytics. The result is returned on every video as platform_signals, also on the order progress page and in Analytics. The object is always present; every field is null until the first check — null means not checked yet, never no.

"platform_signals": {
  "checked_at": "2026-09-22T05:47:52Z",
  "not_recommended": true,
  "not_recommended_since": "2026-09-19T05:28:00Z",
  "ai_label": null,
  "sound": "non_commercial",
  "sound_reason": "Can't promote due to audio copyright issue"
}

The same observations are pushed as webhooks the moment they are detected: video.not_recommended, video.ai_labeled and video.sound_restricted. Portfolio-wide, GET /analytics/signals lists every flagged post.

Publish Date Rules

The target_publish_date field controls when the video should be published.

• Account still being created (not yet delivered): minimum 3 days from today.
• Account already delivered, or a bundle running on an existing account: minimum 1 day from today.

A bundle can also carry at most 3 videos targeting the same day. Dates earlier than the allowed minimum are rejected with a VALIDATION_ERROR.

List All Videos in a Bundle

Retrieve every video configured for a bundle.

GET /bundles/:id/videos

curl -X GET https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos \
  -H "X-API-Key: sk_xxx"

Response:

{
  "data": [
    {
      "position": 1,
      "video_type": "video",
      "status": "configured",
      "description": "Unboxing the new product line",
      "target_publish_date": "2026-03-15",
      "video_url": "https://pub-xxx.r2.dev/videos/abc123.mp4",
      "external_ref": "campaign-42-v1",
      "download_issue": false,
      "download_issue_comment": null
    },
    {
      "position": 2,
      "video_type": "carousel",
      "status": "pending",
      "description": null,
      "target_publish_date": null,
      "video_url": null,
      "external_ref": null,
      "download_issue": false,
      "download_issue_comment": null
    }
  ]
}

Get a Single Video

GET /bundles/:id/videos/:position

curl -X GET https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos/1 \
  -H "X-API-Key: sk_xxx"

Response:

{
  "data": {
    "position": 1,
    "video_type": "video",
    "status": "configured",
    "description": "Unboxing the new product line",
    "target_publish_date": "2026-03-15",
    "video_url": "https://pub-xxx.r2.dev/videos/abc123.mp4",
    "tiktok_sound_url": "https://www.tiktok.com/music/original-sound-123",
    "editing_instructions": "Add brand logo at the end",
    "external_ref": "campaign-42-v1",
    "download_issue": false,
    "download_issue_comment": null,
    "platform_signals": {
      "checked_at": null,
      "not_recommended": null,
      "not_recommended_since": null,
      "ai_label": null,
      "sound": null,
      "sound_reason": null
    }
  }
}

What's Next