> ## 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` and `GET /v1/videos/{id}/publish`.

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 existing completed export. Call `export_video` with the settings you want, poll `get_export_status` until it is `completed`, then pass the same `export` settings to `publish_to_social`. If no completed export matches, the call returns a `conflict` error.
* TikTok isn't available: its consent form must be completed in the Tella app.

**Typical agent flow:**

1. `export_video` with `{videoId}` (and any `resolution`, `fps`, `subtitles`, `speed`)
2. `get_export_status` until `completed`
3. Confirm the destination, text and privacy with the user
4. `publish_to_social` with the same `export` settings. It returns a `queued` publication
5. `list_social_publications` until that destination is `completed` (read its `url`) or `failed` (read its `error`)

## publish\_to\_social

Start a publish to one destination. Returns immediately with a `queued` publication. One publish per destination runs at a time; starting another while one is `queued` or `running` returns a `conflict` error. Publishing again after one completes creates a second post.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="destination" type="enum<string>" 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)
</ParamField>

<ParamField path="title" type="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
</ParamField>

<ParamField path="description" type="string">
  YouTube description, or the post text on LinkedIn, X, Instagram and Facebook. Stories show no text
</ParamField>

<ParamField path="privacy" type="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
</ParamField>

<ParamField path="export" type="object">
  Settings of the completed export to upload, exactly as passed to `export_video`. Omit for the default export: 1080p, 30 fps, no burned-in subtitles, 1x

  <Expandable title="properties">
    <ParamField path="resolution" type="enum<string>">`4k`, or omit for 1080p</ParamField>
    <ParamField path="fps" type="enum<string>">`30` or `60`</ParamField>
    <ParamField path="subtitles" type="boolean">Burned-in subtitles</ParamField>
    <ParamField path="speed" type="enum<string>">`0.5`, `0.75`, `1`, `1.25`, `1.5`, `1.75` or `2`</ParamField>
  </Expandable>
</ParamField>

<ParamField path="uploadCaptions" type="boolean">
  YouTube only: upload the transcript as a caption track (default `true`). Skipped when the export has burned-in subtitles
</ParamField>

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.

## list\_social\_publications

The latest publish of a video to each destination, including publishes made in the Tella app (TikTok among them). Poll this after `publish_to_social`.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

Each publication has:

<ResponseField name="destination" type="string">
  One of the `publish_to_social` destinations, or `tiktok`
</ResponseField>

<ResponseField name="status" type="enum<string>">
  `queued`, `running`, `completed` or `failed`
</ResponseField>

<ResponseField name="url" type="string | null">
  The post on the destination, once `completed`
</ResponseField>

<ResponseField name="error" type="string | null">
  Why a `failed` publish failed
</ResponseField>

<ResponseField name="captionsError" type="string | null">
  Set on a `completed` YouTube publish whose caption track YouTube refused
</ResponseField>

<ResponseField name="title" type="string">
  The title sent
</ResponseField>

<ResponseField name="privacy" type="enum<string>">
  `public`, `unlisted` or `private`, or TikTok's `followers` or `friends`
</ResponseField>

<ResponseField name="providerVideoId" type="string | null">
  The platform's ID for the post
</ResponseField>

<ResponseField name="createdAt" type="string">
  When the publish started
</ResponseField>

<ResponseField name="updatedAt" type="string">
  When its status last changed
</ResponseField>

## 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](/docs/help/integrations/overview.md)
- [Publish to social media with the API or MCP](/docs/help/integrations/publish-with-the-api-and-mcp.md)
- [Model Context Protocol (MCP)](/docs/mcp-server.md)
- [Publish a video to social media](/docs/help/sharing/publish-to-social-media.md)
- [Video requirements for each social platform](/docs/help/sharing/social-publishing-requirements.md)