> ## Documentation Index > Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Social publishing > Publish a video to the user's connected YouTube, LinkedIn, X, Instagram and Facebook accounts, and check on each publish. 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. **videoId** `string` *required* Video ID **destination** `enum\` *required* `youtube`, `youtube_shorts`, `linkedin`, `x`, `instagram_post`, `instagram_reel`, `instagram_story`, `facebook_post` or `facebook_story`. The Instagram and Facebook destinations publish through one Facebook connection. See [limits](#destination-limits) **title** `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 **description** `string` YouTube description, or the post text on LinkedIn, X, Instagram and Facebook. Stories show no text **privacy** `enum\` `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 **export** `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 **properties** **resolution** `enum\` `4k`, or omit for 1080p **fps** `enum\` `30` or `60` **subtitles** `boolean` Burned-in subtitles **speed** `enum\` `0.5`, `0.75`, `1`, `1.25`, `1.5`, `1.75` or `2` **uploadCaptions** `boolean` YouTube only: upload the transcript as a caption track (default `true`). Skipped when the export has burned-in subtitles **accountId** `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 **scheduledAt** `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 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`. **videoId** `string` *required* Video ID **destination** `enum\` *required* The publication's `destination`, from `list_social_publications` **accountId** `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: **id** `string` Pass as `accountId` to `publish_to_social` **name** `string | null` The account's name in Tella: the one the user gave it in **Settings** → **Connections**, else its name on the platform **destinations** `string[]` The destinations it posts to. A YouTube account posts to both `youtube` and `youtube_shorts` **connected** `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`. **videoId** `string` *required* Video ID Each publication has: **destination** `string` One of the `publish_to_social` destinations, or `tiktok` **accountId** `string | null` The connected account it was published with. `null` for publishes made before Tella supported several accounts **accountName** `string | null` That account's name in Tella when the publish started **status** `enum\` `queued`, `running`, `completed`, `failed` or `cancelled`. A scheduled publish stays `queued` until its time **scheduledAt** `string | null` When a scheduled publish goes out. `null` when it wasn't scheduled **url** `string | null` The post on the destination, once `completed` **error** `string | null` Why a `failed` publish failed **captionsError** `string | null` Set on a `completed` YouTube publish whose caption track YouTube refused **title** `string` The title sent **privacy** `enum\` `public`, `unlisted` or `private`, or TikTok's `followers` or `friends` **providerVideoId** `string | null` The platform's ID for the post **createdAt** `string` When the publish started **updatedAt** `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. | Destination | Length | Shape | Other | | - | - | - | - | | `youtube` | Up to 15 minutes from a channel that isn't verified | Any | | | `youtube_shorts` | Up to 3 minutes | Vertical or square | | | `linkedin` | 3 seconds to 30 minutes | Any | Up to 500 MB | | `x` | Up to 20 minutes, or 125 with Premium or a checkmark | Any | | | `instagram_post`, `instagram_reel` | 3 seconds to 15 minutes | Any | Up to 300 MB, no 4K | | `instagram_story` | 3 to 60 seconds | Any | Up to 100 MB, no 4K | | `facebook_post` | | Any | | | `facebook_story` | 3 to 60 seconds | Vertical | | 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. ## Related topics - [Integrations](https://www.tella.com/docs/help/integrations/overview.md) - [Publish to social media with the API or MCP](https://www.tella.com/docs/help/integrations/publish-with-the-api-and-mcp.md) - [Model Context Protocol (MCP)](https://www.tella.com/docs/mcp-server.md) - [Publish a video to social media](https://www.tella.com/docs/help/sharing/publish-to-social-media.md) - [Connect your social accounts](https://www.tella.com/docs/help/integrations/connect-social-accounts.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.