> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

# Linking Twelve Labs as a source

Canonical URL: https://posthog.com/docs/data-pipelines/sources/twelve-labs

> **Cloud region:** This page uses US Cloud hosts. For an EU Cloud project, use `https://eu.posthog.com` instead of `https://us.posthog.com` or `https://app.posthog.com` (app host for links).

## On this page

- [Prerequisites](#prerequisites)
- [Adding a data source](#adding-a-data-source)
- [Sync modes](#sync-modes)
- [Configuration](#configuration)
- [Supported tables](#supported-tables)
- [Troubleshooting](#troubleshooting)

**Beta release**

This source is currently in **beta**. It works end to end, but you may still hit rough edges. [Let us know](https://us.posthog.com/#panel=support%3Asupport%3Adata_warehouse%3A%3Atrue) if you do.

![](https://res.cloudinary.com/dmukukwp6/image/upload/texture_tan_9608fcca70)

![](https://res.cloudinary.com/dmukukwp6/image/upload/texture_tan_dark_a92b0e022d)

Let AI connect your sources for you

Skip the manual setup — run this in your project and the wizard auto-detects your databases and APIs and connects them to PostHog.

`npx @posthog/wizard warehouse`

![PostHog Wizard hedgehog](https://res.cloudinary.com/dmukukwp6/image/upload/wizard_3f8bb7a240.png)

![](https://res.cloudinary.com/dmukukwp6/image/upload/wizard_3f8bb7a240.png)Let AI connect your sources for you

Sync your [Twelve Labs](https://www.twelvelabs.io) video understanding library into PostHog. This connector imports your indexes, the videos in each index, the video indexing tasks that track the upload and indexing lifecycle, the transcriptions of your video and audio assets, and the tags on your knowledge store video items, so you can analyze library growth, indexing throughput, indexing failures, and spoken content alongside the rest of your data.

## Prerequisites

You need a Twelve Labs account and an API key. Any plan tier works, but free plans have daily request caps that can slow the sync of very large libraries.

## Adding a data source

1.  In PostHog, go to the [Sources tab](https://app.posthog.com/data-management/sources) of the data pipeline section.
2.  Click **\+ New source** and click **Link** next to this source.
3.  Enter your credentials (see [Configuration](#configuration) below) and click **Next**.
4.  Select the tables you want to sync, choose a sync method and frequency, then click **Import**.

Once the syncs are complete, you can start querying this data in PostHog.

You need your **Twelve Labs API key**. You can create one from the [API key page](https://playground.twelvelabs.io/dashboard/api-key) in your Twelve Labs dashboard. Paste it into the API key field when connecting the source.

## Sync modes

Each table can be synced in one of several modes, depending on what the source supports:

-   **Webhook** (when available) – the source pushes changes to PostHog in real time. Fastest freshness, lowest ongoing cost, and the only mode that reliably captures updates and deletes.
-   **Incremental** – only new or updated rows are synced on each run, using a cursor field (such as an `updated_at` timestamp). Cheaper than a full refresh, but deletes aren't captured.
-   **Append only** – new rows are appended using a cursor field; existing rows are never updated. Ideal for immutable, append-only tables like event logs.
-   **Full refresh** – the whole table is reloaded on every sync. Use it when a table has no reliable cursor or when you need deletions reflected.

See [sync methods](https://posthog.com/docs/data-pipelines/sources.md#sync-methods) for a full explanation of how each mode works and how to choose between them.

`indexes` and `tasks` support incremental sync (via the server-side `updated_at` filter) and are recommended for ongoing syncs. `videos` is nested per index and syncs by full refresh; it is disabled by default because fanning out one request per index can consume a meaningful share of a free plan's daily request quota. Enable it when you need per-video metadata.

`asset_transcriptions` works the same way: it makes one request per video or audio asset, syncs by full refresh, and is disabled by default. Each row holds the transcription status plus its sentences and speaker turns. Assets without a transcription are skipped.

`knowledge_store_item_tags` holds the tags on the video items of your knowledge stores. Each row is one tag with its start and end time and its custom metadata. It makes one request per knowledge store and one per video item, syncs by full refresh, and is disabled by default.

## Configuration

| Option | Type | Required |
| --- | --- | --- |
| `API key` | password | Yes |

## Supported tables

| Table | Description | Sync method | Incremental field | Primary key |
| --- | --- | --- | --- | --- |
| `indexes` | An index groups one or more uploaded videos stored as vectors, together with the models used to process them. | Incremental, Full refresh | updated\_at, created\_at | — |
| `tasks` | A video indexing task tracks the upload and indexing lifecycle of a single video. | Incremental, Full refresh | updated\_at, created\_at | — |
| `videos` | A video is an indexed asset within an index, searchable and available for analysis. | Full refresh | — | — |
| `asset_transcriptions` | The speech transcription of a video or audio asset, with its status and timestamped segments. | Full refresh | — | — |
| `knowledge_store_item_tags` | An item tag marks a moment or a range of a knowledge store video item and carries custom metadata. | Full refresh | — | — |

## Troubleshooting

If the connection fails with an authorization error, confirm your API key is active in the Twelve Labs dashboard and has not been revoked. If a large library syncs slowly, it is most likely being throttled by your plan's daily request cap; syncing fewer tables or upgrading your plan will help.

If your sync is failing or data looks wrong, see the [Data warehouse troubleshooting guide](https://posthog.com/docs/data-warehouse/troubleshooting.md). If that doesn't help, [contact support](https://us.posthog.com/#panel=support%3Asupport%3Adata_warehouse%3A%3Atrue) – we're happy to help.