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"
}