Skip to main content
Post a video to one of the user’s connected social accounts, then poll for the result. The REST equivalents are POST, GET and DELETE /v1/videos/{id}/publish, and GET /v1/social-accounts. A publish posts under the user’s own account, often publicly, so confirm the destination, text and privacy with the user before calling publish_to_social. Before publishing:
  • The account must already be connected in Tella, under Settings → Connections or Share → Publish. These tools can’t connect one; an unconnected destination returns a forbidden error.
  • Publishing uploads an export with the export settings you pass. Tella reuses a finished or running export with those settings, or starts one, so you don’t need to call export_video first. The publication stays queued while the export renders. A plan that doesn’t include the export’s resolution or frame rate returns a forbidden error.
  • TikTok isn’t available: its consent form must be completed in the Tella app.
  • A user can connect several accounts per platform, such as two YouTube channels. Call list_social_accounts and pass the chosen one’s id as accountId. Without it, the oldest connected account for the destination posts.
Typical agent flow:
  1. list_social_accounts if the user has several accounts for the destination
  2. Confirm the destination, account, text and privacy with the user
  3. publish_to_social with any export settings (resolution, fps, subtitles, speed), once per account. Each call returns a queued publication
  4. list_social_publications until each publication is completed (read its url) or failed (read its error)
To post later, pass scheduledAt to publish_to_social. The publication stays queued with that scheduledAt until its time, and cancel_scheduled_publication takes it back before then. Tella exports the video right away, so edits made after scheduling aren’t in the post.

publish_to_social

Start a publish to one destination and account. Returns immediately with a queued publication. One publish per destination and account runs at a time; starting another to the same account while one is queued or running returns a conflict error. Publishes to different accounts run side by side. Publishing again after one completes creates a second post.
string
required
Video ID
enum<string>
required
youtube, youtube_shorts, linkedin, x, instagram_post, instagram_reel, instagram_story, facebook_post, facebook_reel or facebook_story. The Instagram and Facebook destinations publish through one Facebook connection. See limits
string
required
Video title on YouTube. On LinkedIn, X, Instagram and Facebook it is the post text when description is empty. Must not be empty
string
YouTube description, or the post text on LinkedIn, X, Instagram and Facebook. Stories show no text
enum<string>
public, unlisted or private. Defaults to the most private option the destination offers:
  • youtube, youtube_shorts: private (default), unlisted or public
  • linkedin: private (connections only, default) or public
  • facebook_post: private (only people who manage the Page, default), unlisted (anyone with the link) or public
  • every other destination: public only
object
Settings of the export to upload, as export_video takes them. A finished or running export with these settings is reused; otherwise one is started. Omit for the default export: 1080p, 30 fps, no burned-in subtitles, 1x
boolean
YouTube only: upload the transcript as a caption track (default true). Skipped when the export has burned-in subtitles
string
Which connected account to post with, from list_social_accounts. Defaults to the oldest connected account for the destination. An accountId that isn’t one of the user’s connected accounts for the destination returns a forbidden error
string
When to post, as an ISO 8601 time with a timezone, such as 2026-10-20T15:00:00Z, at most 30 days ahead. Omit to post as soon as the export is ready. A time in the past or more than 30 days ahead returns a bad_request error
enum<string>
instagram_reel only: share it as a trial reel, shown to people who don’t follow the account first. manual keeps it a trial until you share it with followers in the Instagram app; performance lets Instagram share it with followers if it performs well. Omit for an ordinary reel. Passing it with any other destination returns a bad_request error
Facebook destinations post to the default Page set in Settings → Connections, else the first Page the account manages. Instagram destinations likewise post to the default Instagram account. Unlike the app, publish_to_social doesn’t append chapters to a YouTube description; read them with get_chapters and include them in description if you want them.

cancel_scheduled_publication

Cancel a scheduled publish before it goes out. Only a publication that is still queued with a scheduledAt can be cancelled; once it starts going out, this returns a conflict error. Returns the publication with status cancelled.
string
required
Video ID
enum<string>
required
The publication’s destination, from list_social_publications
string
The publication’s accountId, from list_social_publications

list_social_accounts

The accounts the user has connected in Tella that publish_to_social can post with. Takes no parameters. Each account has:
string
Pass as accountId to publish_to_social
string | null
The account’s name in Tella: the one the user gave it in Settings → Connections, else its name on the platform
string[]
The destinations it posts to. A YouTube account posts to both youtube and youtube_shorts
boolean
false when the account needs reconnecting in Tella before it can publish

list_social_publications

The latest publish of a video to each destination and account, including publishes made in the Tella app (TikTok among them). Poll this after publish_to_social.
string
required
Video ID
Each publication has:
string
One of the publish_to_social destinations, or tiktok
string | null
The connected account it was published with. null for publishes made before Tella supported several accounts
string | null
That account’s name in Tella when the publish started
enum<string>
queued, running, completed, failed or cancelled. A scheduled publish stays queued until its time
string | null
When a scheduled publish goes out. null when it wasn’t scheduled
string | null
The post on the destination, once completed
string | null
Why a failed publish failed and what to do next, as a sentence you can show to people. It never contains the destination’s raw response
string | null
Set on a completed YouTube publish whose caption track YouTube refused
string
The title sent
enum<string>
public, unlisted or private, or TikTok’s followers or friends
string | null
The platform’s ID for the post
string
When the publish started
string
When its status last changed

Destination limits

Tella checks these before starting a publish and returns a bad_request error naming the rule a video breaks. Lengths are of the export, so a 2x export is half as long. File size is checked after the export, just before uploading, so an oversized export shows up as a failed publication rather than an error on the call.
Last modified on November 8, 2026