Post

Video or slideshow post data structure

Overview

Represents a video or slideshow post on a social media account.

Fields

Field	Type	Description
id	string	Unique post identifier
account_id	string | null	ID of the account that created this post. null for draft posts not yet assigned to an account.
type	'video' | 'slideshow'	Type of post content
status	string	Current status: 'draft', 'scheduled', 'pending', 'complete', or 'failed'
social_id	string | null	Platform-specific post ID (TikTok video ID or Instagram reel code, available after posting)
caption	string | null	Post caption/description text (max 4000 characters)
tag	string | null	Custom tag for categorization. Set via the post_tag parameter on create/update endpoints.
caption_overlays	CaptionOverlay[] | null	Text overlays to display on the video. Each is { text, x, y, fontSize } — x/y are the overlay center as a fraction (0-1) of the video width/height, fontSize is a fraction (0-1) of the video height. Only used for video posts.
media_urls	string[] | null	Array of URLs to video/image files used in the post
thumbnail_url	string | null	URL of a JPEG thumbnail image generated from the first frame of a video post. Only present for video posts.
music_post_id	string | null	ID of the music/audio track used in the post
scheduled_at	string | null	When the post is scheduled to be published (ISO 8601 format)
postUrl	string | undefined	Direct URL to view the post on the social platform. Only available when status is 'complete'. Format: TikTok: https://www.tiktok.com/@username/video/{social_id}, Instagram: https://www.instagram.com/p/{social_id}/

Post Status Values

Status	Description	Can Delete?
draft	Post is saved but not assigned to an account or scheduled	✅ Yes
scheduled	Post is scheduled to be published at a future time	✅ Yes
pending	Post is currently being processed/published	✅ Yes
complete	Post was successfully published to the platform	❌ No
failed	Post failed to publish (check error logs)	✅ Yes
retrying	Post is being retried after a previous failure	✅ Yes

Posts with status complete (already published) cannot be deleted via the API to prevent accidental removal of live content. Only unpublished, pending, or failed posts can be deleted using the Delete Posts endpoint.

Post Types

Type	Description
video	Single video post
slideshow	Multiple images with music/audio

Example Responses

Complete TikTok Post

{
  "id": "post_abc123",
  "account_id": "acc_123456",
  "type": "video",
  "status": "complete",
  "social_id": "7234567890123456789",
  "caption": "Check out this awesome video! 🎥 #viral",
  "media_urls": [
    "https://storage.example.com/video1.mp4"
  ],
  "music_post_id": "music_xyz789",
  "scheduled_at": "2024-01-15T14:30:00Z",
  "postUrl": "https://www.tiktok.com/@username/video/7234567890123456789"
}

Complete Instagram Post

{
  "id": "post_def456",
  "account_id": "acc_789012",
  "type": "video",
  "status": "complete",
  "social_id": "ABC123xyz",
  "caption": "Amazing content! ✨ #instagram",
  "media_urls": [
    "https://storage.example.com/video2.mp4"
  ],
  "music_post_id": "music_xyz789",
  "scheduled_at": "2024-01-15T16:00:00Z",
  "postUrl": "https://www.instagram.com/p/ABC123xyz/"
}

Scheduled Post (no postUrl)

{
  "id": "post_ghi789",
  "account_id": "acc_123456",
  "type": "slideshow",
  "status": "scheduled",
  "social_id": null,
  "caption": "Coming soon! 🎬",
  "media_urls": [
    "https://storage.example.com/img1.jpg",
    "https://storage.example.com/img2.jpg"
  ],
  "music_post_id": "music_abc123",
  "scheduled_at": "2024-01-20T10:00:00Z"
}