> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tella as a data source

> Bring videos, playlists, tags and viewing analytics from Tella to Nekt.

Tella is a screen-recording tool for creating, editing and sharing videos such as product demos, tutorials and sales videos. This connector reads your Tella workspace through the Tella Public API and brings your videos (with duration, chapters and transcript), playlists, playlist groups and tags, plus viewing analytics: plays per video per day, workspace totals per day and a 30-day summary per video with retention, countries, referrers, UTM sources and call-to-action clicks.

> [!NOTE]
>
> The connector only reads data. It never creates, changes or deletes anything in Tella, and it never downloads the video files.

> [!WARNING]
>
> **Not on Tella Premium? Do not run a Full sync or an Additional Full Sync on Video Daily Analytics or Workspace Daily Analytics.** Without Premium, Tella only gives access to the last 30 days of analytics, so a full sync replaces everything Nekt has accumulated in those two tables with the last 30 days only, and the older days cannot be fetched again. Keep these two tables on incremental syncs.

## Configuring Tella as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Tella option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

The connector signs in with a Tella **API key**. The key reads Tella as the person who created it: the videos, playlists and analytics this person can see.

To create a key:

1. In Tella, open **Settings** and go to **API keys**.
2. Create a new key (for example named "Nekt") and copy it. It starts with `tella_pk_`.

See [Tella's authentication guide](https://www.tella.com/docs/authentication).

The following configurations are available:

* **API Key**: The Tella API key.
* **Start Date**: The first day of the daily analytics tables (Video Daily Analytics and Workspace Daily Analytics). The other tables are always read in full.

> [!WARNING]
>
> Without a Tella **Premium** plan, Tella only gives access to the **last 30 days** of analytics. On other plans the daily analytics tables start 30 days before the first sync, whatever the Start Date, and the sync log says so. From then on the history builds up in Nekt with each sync, so keep the source running at least once every few weeks. **Do not run a Full sync or an Additional Full Sync on the daily analytics tables**: it would keep only the last 30 days.

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

> Tip: The stream can be found more easily by typing its name.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
  * Incremental: every time the extraction happens, we'll get only the new data, which is good if, for example, you want to keep every record ever fetched.
  * Full table: every time the extraction happens, we'll get the current state of the data, which is good if, for example, you don't want to have deleted data in your catalog.

> [!WARNING]
>
> Keep **Video Daily Analytics** and **Workspace Daily Analytics** on **Incremental** unless your Tella workspace is on Premium. As Full table they would hold only the last 30 days.

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers.md), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can define some additional settings:

* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while. **Do not enable it for the daily analytics tables unless your Tella plan is Premium** (see the warnings above).

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.

# Streams and Fields

## Available streams

The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API) and a short description.

| Stream | Slug | Sync | Description |
| - | - | - | - |
| Account | `account` | Full table | The workspace, the user who created the API key, their role and the workspace plan. |
| Tags | `tags` | Full table | Workspace tags and the user's private tags. |
| Playlist Groups | `playlist_groups` | Full table | Groups that organize playlists in the Tella sidebar. |
| Playlists | `playlists` | Full table | The user's personal playlists and the playlists shared with the workspace. |
| Videos | `videos` | Full table | Every video of the user, with duration, chapters, transcript, settings and lifetime view count. |
| Video Tags | `video_tags` | Full table | Which tags are on which video. |
| Video Daily Analytics | `video_daily_analytics` | Incremental | Plays, sessions and average share watched per video per day. |
| Workspace Daily Analytics | `workspace_daily_analytics` | Incremental | Workspace totals per day: plays, sessions, watch time, page opens, countries and referrers. |
| Video Analytics | `video_analytics` | Full table | Last 30 days per video: totals, retention curve, countries, referrers, UTM sources and call-to-action clicks. |

> [!NOTE]
>
> Tella's API has no list of individual views or viewers, and no comments. Analytics come as totals per day (daily tables) or per period (Video Analytics). Nested information (chapters, thumbnails, settings, breakdowns, retention) comes as JSON text. Thumbnail and export addresses are signed by Tella and stop working after a while.

## Fields by stream

### Workspace

> [accordion] Account
>
> One row: the workspace, the user who created the API key and the workspace plan. Read in full on every sync.
>
> Table: `account` · Primary key: `workspace_id`, `user_id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `workspace_id` | String | Unique identifier of the Tella workspace. |
> | `workspace_name` | String | Name of the Tella workspace. |
> | `user_id` | String | Unique identifier of the user who owns the API key. |
> | `user_name` | String | Name of the user who owns the API key. |
> | `user_email` | String | E-mail of the user who owns the API key. |
> | `role` | String | Role of the user in the workspace (owner, member, viewer). |
> | `plan_name` | String | Workspace plan (free, pro, premium, enterprise, enterprise-premium). |
> | `plan_status` | String | Subscription status of the plan (active, trialing, past\_due, ...); empty on the Free plan. |
> | `plan_trial_ends_at` | Datetime | When the trial ends, while trialing. |
> | `plan_cancels_at_period_end` | Boolean | Whether the subscription is set to cancel at the end of the current period. |
> | `credits_balance` | Number | Agent credits left in the workspace. |
> | `credits_monthly_allowance` | Number | Agent credits the plan grants each month. |
> | `billing_url` | String | Link to the workspace's billing page. |

> [accordion] Tags
>
> Every tag the API key's user can see: tags shared with the workspace and the user's private tags. Read in full on every sync.
>
> Table: `tags` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the tag. |
> | `name` | String | Tag name. |
> | `description` | String | Optional tag description. |
> | `color` | String | Tag color as a hex value. |
> | `scope` | String | Visibility: 'workspace' tags are shared with everyone, 'private' tags only with their owner. |

> [accordion] Playlist Groups
>
> The groups that organize playlists in the Tella sidebar, in sidebar order. Read in full on every sync.
>
> Table: `playlist_groups` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the playlist group. |
> | `name` | String | Playlist group name. |
> | `emoji` | String | Emoji of the group; empty when unset. |
> | `visibility` | String | 'personal' (only visible to the API key's user) or 'org' (shared with the workspace). |
> | `sidebar_position` | Integer | Position of the group in the sidebar, starting at 0 (the API's order). |

> [accordion] Playlists
>
> The user's personal playlists and every playlist shared with the workspace. Read in full on every sync. Which videos are in a playlist is in the `playlist_ids` field of Videos.
>
> Table: `playlists` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the playlist. |
> | `name` | String | Playlist name. |
> | `description` | String | Playlist description. |
> | `emoji` | String | Emoji of the playlist. |
> | `group_id` | String | Playlist group the playlist belongs to in the sidebar (see playlist\_groups); null if ungrouped. |
> | `visibility` | String | 'personal' (only its creator) or 'org' (shared with the workspace). |
> | `link_scope` | String | Who can open the playlist link: public, private, password or embedonly. |
> | `search_engine_indexing_enabled` | Boolean | Whether search engines can index the playlist page. |
> | `video_count` | Integer | Number of videos in the playlist. |
> | `view_page_url` | String | URL of the playlist page on Tella. |
> | `created_at` | Datetime | When the playlist was created. |
> | `updated_at` | Datetime | When the playlist was last updated. |

### Videos

> [accordion] Videos
>
> Every video of the API key's user, with the details of each one. One request per video on every sync, so titles, settings and the view count are always current.
>
> Table: `videos` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the video. |
> | `name` | String | Video title. |
> | `description` | String | Video description. |
> | `views` | Integer | Total view count of the video at the time of the sync (Tella's lifetime counter). |
> | `duration_seconds` | Number | Video duration in seconds. |
> | `aspect_ratio` | String | Video aspect ratio (e.g. '16:9', '9:16'). |
> | `auto_ratio` | Boolean | Whether the canvas follows the recording's own size (the editor's Size > Auto setting). |
> | `width` | Number | Canvas width in pixels. |
> | `height` | Number | Canvas height in pixels. |
> | `link_scope` | String | Who can open the video link (e.g. public, private, password, embedonly, org). |
> | `view_page_url` | String | URL to watch the video on Tella. |
> | `embed_page_url` | String | URL to embed the video. |
> | `playlist_ids` | Array of strings | Identifiers of the playlists that contain this video (see the playlists stream). |
> | `clip_ids` | Array of strings | Ordered identifiers of the clips (recorded scenes) that make up the video. |
> | `chapters` | String | Video chapters as a JSON array of objects (title, description, timestampSeconds). |
> | `transcript_status` | String | Status of the automatic transcript generation. |
> | `transcript_language` | String | Language code detected for the transcript (e.g. 'en', 'pt'). |
> | `transcript_text` | String | Full transcript text of the video. |
> | `thumbnails` | String | Thumbnail URLs by size and format, as a JSON object (signed URLs that expire). |
> | `exports` | String | Exports of the video and their status, as a JSON array (download URLs expire). |
> | `background_music` | String | Video-wide background music track, as a JSON object; null when there is none. |
> | `settings` | String | Playback, sharing and editing settings of the video (comments, downloads, captions, call-to-action buttons, ...), as a JSON object. |
> | `created_at` | Datetime | When the video was created. |
> | `updated_at` | Datetime | When the video was last updated. |

> [accordion] Video Tags
>
> One row per video and tag. One request per video on every sync.
>
> Table: `video_tags` · Primary key: `video_id`, `tag_id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `video_id` | String | Identifier of the video (see the videos stream). |
> | `tag_id` | String | Identifier of the tag (see the tags stream). |
> | `tag_name` | String | Tag name. |
> | `tag_scope` | String | 'workspace' (shared) or 'private' (only visible to the API key's user). |

### Analytics

> [accordion] Video Daily Analytics
>
> Plays per video per day (UTC days), for the videos with at least one play that day: a video with no plays on a day has no row for that day. Covers the videos shared with the workspace and the videos the API key's user created. Incremental: each sync reads again the last 3 days already loaded (today's numbers are still growing) and then every day up to today; the first sync starts at the Start Date.
>
> Table: `video_daily_analytics` · Primary key: `video_id`, `date` · Sync: Incremental (`date`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `video_id` | String | Identifier of the video (see the videos stream). |
> | `date` | Date | UTC day the numbers refer to; used as the incremental replication key. |
> | `video_name` | String | Video title; null when the video was deleted (its plays still count). |
> | `views` | Integer | Plays that day (a play counts once a viewer starts the video). |
> | `unique_sessions` | Integer | Distinct viewer sessions that started a play that day. |
> | `avg_percent_viewed` | Number | Average share of the video watched per play that day, from 0 to 100. |

> [accordion] Workspace Daily Analytics
>
> Totals per day (UTC days) for every video shared with the workspace, one row per day, including days without plays. Incremental, same as Video Daily Analytics.
>
> Table: `workspace_daily_analytics` · Primary key: `date` · Sync: Incremental (`date`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `date` | Date | UTC day the numbers refer to; used as the incremental replication key. |
> | `total_views` | Integer | Plays that day across every video shared with the workspace. |
> | `unique_sessions` | Integer | Distinct viewer sessions that started a play. |
> | `total_watch_time_seconds` | Number | Total time viewers spent watching, in seconds. |
> | `avg_percent_viewed` | Number | Average share of a video watched per play, from 0 to 100; null when nothing was watched. |
> | `page_opens` | Integer | Times a video page was opened, whether or not playback started (automated visits excluded). |
> | `geo_breakdown` | String | Plays by country (ISO code, views, uniqueSessions), up to 100 rows, as a JSON array. |
> | `referrer_breakdown` | String | Plays by referring domain (referrerDomain, views, uniqueSessions), up to 100 rows, as a JSON array. |
> | `retention` | String | Watch counts per one-percent slice of the videos (percent, watchCount, uniqueViewers), as a JSON array. |

> [accordion] Video Analytics
>
> Summary of the last 30 days (ending on the day of the sync) for every video with at least one play in that period. The whole table is replaced on every sync.
>
> Table: `video_analytics` · Primary key: `video_id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `video_id` | String | Identifier of the video (see the videos stream). |
> | `video_name` | String | Video title. |
> | `window_start` | Date | First UTC day of the window the numbers cover. |
> | `window_end` | Date | Last UTC day of the window (the day of the sync). |
> | `total_views` | Integer | Plays in the window. |
> | `unique_sessions` | Integer | Distinct viewer sessions that started a play. |
> | `total_watch_time_seconds` | Number | Total time viewers spent watching the video, in seconds. |
> | `avg_percent_viewed` | Number | Average share of the video watched per play, from 0 to 100. |
> | `page_opens` | Integer | Times the video page was opened, whether or not playback started. |
> | `cta_clicks` | Integer | Clicks on the video's call-to-action button. |
> | `retention` | String | Watch counts per one-percent slice of the video (percent, watchCount, uniqueViewers), as a JSON array. |
> | `geo_breakdown` | String | Plays by country (ISO code, views, uniqueSessions), up to 100 rows, as a JSON array. |
> | `referrer_breakdown` | String | Plays by referring domain (referrerDomain, views, uniqueSessions), up to 100 rows, as a JSON array. |
> | `traffic_sources` | String | Plays by UTM source, medium and campaign, up to 100 rows, as a JSON array. |

## Implementation Notes

### Data Quality Considerations

* **What the key can see is what you get.** The connector reads Tella as the person who created the API key. Videos shared with that person only as a collaborator (not shared with the workspace and not created by them) are not in the analytics tables.
* **Days are UTC days.** A play at 22:00 in Brasília (01:00 UTC) counts on the next day.
* **Today's numbers are partial** and are completed by the next syncs, which always read the last 3 days again.
* **Deleted videos** still count in the analytics of the days they were watched (their `video_name` is empty), but they leave the Videos, Video Tags and Video Analytics tables.
* **Lifetime views**: `views` in Videos is Tella's total counter at the time of the sync. For plays per day use Video Daily Analytics.
* **Analytics history**: without a Premium plan only the last 30 days are available (see the warning in the configuration section).
* **Days whose plays per video do not add up to Tella's daily total.** Tella's total can differ slightly from the sum of its per-video numbers (for example when a deleted video or a filtered visit is counted in only one of them). The connector reads such a day twice: if Tella returns the same numbers both times, the rows are loaded and the sync log lists the days and both numbers. Only if Tella returns a different list of videos each time, and they still do not add up, the Video Daily Analytics table is not updated and the next sync tries again; if that keeps happening for one day, move the source's Start Date to the day after it, or contact Nekt support.
* **Videos that cannot be found**: if most of the videos Tella lists (or all of them, from 3 videos) cannot be found when their details are read, the Videos, Video Tags or Video Analytics table is not updated instead of being saved almost empty.
* **A video whose plays drop to zero** (for example after Tella filters automated visits) keeps its previous row in Video Daily Analytics, because days without plays have no row.

### API Limits & Performance

* Tella allows **200 requests per minute per user**, shared with every other tool that uses the same user's API keys. Videos and Video Tags make one request per video, so a library with thousands of videos takes several minutes per sync.
* **Video Analytics** is limited by Tella to **30 requests per minute for the whole workspace**: one request per video with plays in the last 30 days, so 300 such videos take about 11 minutes. Select it only if you need the retention, UTM or call-to-action data.
* When Tella limits the rate, the sync waits and retries automatically and says so in the sync log.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.