> ## 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. # Figma as a data source > Bring projects, files, file details, version history, comments and published library components and styles from Figma to Nekt. Figma is a collaborative design platform for interface design (Figma Design), whiteboarding (FigJam), presentations (Slides), websites (Sites) and prototypes (Make). This connector reads your Figma teams through the Figma REST API and brings the projects of each team (with their subfolders), every file inside them, the details of each file (type, creator, last editor, link access), the version history of each file, every comment and reply, and the components, component sets and styles published to each team's library. > [!NOTE] > > The connector only reads data. It never creates, changes or deletes anything in Figma, and it never downloads the content (layers and frames) of your design files. ## Configuring Figma 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 Figma 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 Figma **personal access token**. The token reads Figma as the person who generated it, so generate it with a user who is a member of every team you want to extract, ideally with a **Full** or **Dev** seat (see API Limits & Performance below). To generate a token: 1. In Figma, open the file browser, click your account menu in the top-left corner and select **Settings**. 2. Open the **Security** tab and, under **Personal access tokens**, click **Generate new token**. 3. Give the token a name (for example "Nekt"), choose an expiration and give it **read** access to: * **File metadata** * **File versions** * **File comments** * **Folders** (required: without it the sync fails, because Figma would only show the top-level projects and the subfolders would be missing) * **Projects** (used for teams that Figma only lists through its older project routes) * **Team library content** 4. Click **Generate token** and copy it: Figma shows it only once. See [Figma's guide to personal access tokens](https://developers.figma.com/docs/rest-api/personal-access-tokens/). > [!WARNING] > > Personal access tokens expire after at most **90 days**. Generate a new token and update the source before it expires, or the syncs will stop with an authentication error. On **Organization** and **Enterprise** plans an admin can generate a [plan access token](https://developers.figma.com/docs/rest-api/plan-access-tokens/) instead, which is not tied to a person and lasts up to one year; paste it in the same field. You also need the **ID of each team** you want to extract. Figma has no way to list your teams through its API, so they must be informed one by one. Open the team page in Figma (click the team name in the left sidebar of the file browser): the team ID is the number that follows `/team/` in the page address. For example, in `https://www.figma.com/files/181033233908053158/team/1535685101263221741/Design`, the team ID is `1535685101263221741`. You can also paste the whole address. The following configurations are available: * **Access Token**: The Figma personal access token (or plan access token). * **Team IDs**: The IDs of the Figma teams to extract, one per entry. * **Start Date** (optional): The oldest file version to read in the File Versions stream. The other streams are always read in full. > [!WARNING] > > If you leave the **Start Date** empty, the first sync reads the whole version history of every file. Figma saves a version about every 30 minutes of editing, so on teams with many or long-lived files this first sync can take many hours (Figma allows only 5 to 100 version requests per minute, depending on the plan). This first sync is all-or-nothing: if it is interrupted, nothing of it is kept and the next sync starts over, so on large teams we recommend setting a Start Date. The same applies to a full sync of File Versions. Later (incremental) syncs only read the new versions. 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. 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. 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 | | - | - | - | - | | Projects | `projects` | Full table | Projects (Figma now calls them folders) of every team, subfolders included, with their path. | | Files | `files` | Full table | Every file of every project, with its last modification and branches. | | File Metadata | `file_metadata` | Full table | Details of every file: type, creator, last editor, link access and version number. | | File Versions | `file_versions` | Incremental | Version history of every file: named versions and Figma's automatic checkpoints. | | File Comments | `file_comments` | Full table | Every comment and reply of every file, with its position, resolution and reactions. | | Components | `components` | Full table | Components published to each team's library. | | Component Sets | `component_sets` | Full table | Component sets (components with variants) published to each team's library. | | Styles | `styles` | Full table | Color, text, effect and grid styles published to each team's library. | > [!NOTE] > > Files in a person's **Drafts** do not belong to any team, so they are not extracted: move them into a team project to include them. Nested information (comment position and reactions, file branches, a component's frame) comes as JSON text. Every `thumbnail_url` is a temporary address signed by Figma, so it stops working after a while. ## Fields by stream ### Projects and files > [accordion] Projects > > Every project (folder) of the configured teams, including subfolders on plans with nested folders. Read in full on every sync. > > Table: `projects` · Primary key: `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Figma ID of the project (Figma now calls projects folders). | > | `name` | String | Name of the project. | > | `team_id` | String | ID of the team the project belongs to. | > | `team_name` | String | Name of the team the project belongs to. | > | `parent_folder_id` | String | ID of the project (folder) this one is nested in, or empty for a top-level project of the team. | > | `path` | String | Names of the parent projects and of this one, separated by ' / ' (e.g. 'Marketing / Campaigns'). | > | `depth` | Integer | Nesting level: 0 for a top-level project, 1 for a subfolder of it, and so on. | > | `sharing_audience_control` | String | Who can access the project: plan\_view, plan\_edit, invite\_only, workspace\_view or workspace\_edit (only on plans with nested folders). | > | `created_at` | Datetime | When the project was created (only on plans with nested folders). | > [accordion] Files > > Every file of every project: Figma Design, FigJam, Slides, Sites and Make files. Read in full on every sync. > > Table: `files` · Primary key: `key` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `key` | String | Figma file key: the ID in the file's address (figma.com/design/ followed by the key). | > | `name` | String | Name of the file. | > | `last_modified` | Datetime | When the file was last modified (UTC). | > | `thumbnail_url` | String | Address of the file's thumbnail image; Figma signs these addresses and they stop working after a while. | > | `project_id` | String | ID of the project (folder) the file is in. | > | `project_name` | String | Name of the project (folder) the file is in. | > | `team_id` | String | ID of the team the file belongs to. | > | `branches` | String (JSON) | Branches of the file, each with key, name, thumbnail\_url and last\_modified (JSON array; empty when the file has no branches). | ### File details > [accordion] File Metadata > > Details of every file. One request per file on every sync. > > Table: `file_metadata` · Primary key: `file_key` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `file_key` | String | Figma file key (same as `key` in the Files stream). | > | `name` | String | Name of the file. | > | `folder_name` | String | Name of the project (folder) containing the file. | > | `editor_type` | String | Kind of file: figma (design), figjam, slides, buzz, sites or make. | > | `last_touched_at` | Datetime | When the content of the file was last modified (UTC). | > | `last_touched_by_id` | String | Figma user ID of the person who last modified the file. | > | `last_touched_by_handle` | String | Name of the person who last modified the file. | > | `last_touched_by_img_url` | String | Profile picture of the person who last modified the file. | > | `creator_id` | String | Figma user ID of the person who created the file. | > | `creator_handle` | String | Name of the person who created the file. | > | `creator_img_url` | String | Profile picture of the person who created the file. | > | `role` | String | Role of the user who generated the token on this file: owner, editor or viewer. | > | `link_access` | String | Who can open the file with its link: view, edit, org\_view, org\_edit or inherit. | > | `url` | String | Address of the file in Figma. | > | `thumbnail_url` | String | Address of the file's thumbnail image (signed by Figma; stops working after a while). | > | `version` | String | Version number of the file; it changes every time the file is modified. | > [accordion] File Versions > > Version history of every file: the versions people named and the checkpoints Figma saves automatically while a file is edited (about every 30 minutes). Incremental: each sync reads, file by file, only the versions created since the newest one already read (with a one-day margin); a new file is read from the Start Date, or from its first version when the Start Date is empty. > > Table: `file_versions` · Primary key: `file_key`, `id` · Sync: Incremental (`created_at`) > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Figma ID of the version. | > | `file_key` | String | Key of the file the version belongs to. | > | `created_at` | Datetime | When the version was created (UTC), used as the incremental replication key. | > | `label` | String | Name given to the version in Figma; empty for automatic checkpoints. | > | `description` | String | Description given to the version in Figma. | > | `user_id` | String | Figma user ID of the person who created the version. | > | `user_handle` | String | Name of the person who created the version. | > | `user_img_url` | String | Profile picture of the person who created the version. | > | `thumbnail_url` | String | Address of a thumbnail of the file at this version (signed by Figma; stops working after a while). | > [accordion] File Comments > > Every comment and reply of every file. One request per file on every sync, so resolved, edited and deleted comments are always up to date. > > Table: `file_comments` · Primary key: `file_key`, `id` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `id` | String | Figma ID of the comment. | > | `file_key` | String | Key of the file the comment is in. | > | `parent_id` | String | ID of the comment this one replies to; empty for a top-level comment. | > | `order_id` | String | Number shown next to a top-level comment in Figma; empty for replies. | > | `message` | String | Text of the comment. | > | `created_at` | Datetime | When the comment was posted (UTC). | > | `resolved_at` | Datetime | When the comment was resolved (UTC); empty while it is open. | > | `user_id` | String | Figma user ID of the author. | > | `user_handle` | String | Name of the author. | > | `user_img_url` | String | Profile picture of the author. | > | `client_meta` | String (JSON) | Where the comment is pinned: canvas coordinates (x, y) or a frame (node\_id, node\_offset), plus region size for region comments (JSON object). | > | `reactions` | String (JSON) | Emoji reactions to the comment, each with user, emoji and created\_at (JSON array). | ### Team libraries > [accordion] Components > > Components published to each team's library. Read in full on every sync. > > Table: `components` · Primary key: `key` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `key` | String | Unique key of the published item, used to reference it across files. | > | `team_id` | String | ID of the team whose library publishes the item. | > | `file_key` | String | Key of the library file that contains the item. | > | `node_id` | String | ID of the item's node inside the library file. | > | `name` | String | Name of the item. | > | `description` | String | Description written by the publisher. | > | `thumbnail_url` | String | Address of the item's thumbnail image (signed by Figma; stops working after a while). | > | `created_at` | Datetime | When the item was created (UTC). | > | `updated_at` | Datetime | When the item was last updated (UTC). | > | `user_id` | String | Figma user ID of the person who last updated the item. | > | `user_handle` | String | Name of the person who last updated the item. | > | `user_img_url` | String | Profile picture of the person who last updated the item. | > | `page_id` | String | ID of the page of the library file that holds the item. | > | `page_name` | String | Name of the page of the library file that holds the item. | > | `frame_node_id` | String | ID of the frame that contains the item, when there is one. | > | `frame_name` | String | Name of the frame that contains the item, when there is one. | > | `component_set_node_id` | String | ID of the component set (variants) the item belongs to, when there is one. | > | `component_set_name` | String | Name of the component set (variants) the item belongs to, when there is one. | > | `containing_frame` | String (JSON) | Frame that contains the item as Figma sends it: nodeId, name, backgroundColor, pageId, pageName, containingComponentSet (JSON object). | > [accordion] Component Sets > > Component sets (components with variants) published to each team's library. Read in full on every sync. Same fields as Components. > > Table: `component_sets` · Primary key: `key` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `key` | String | Unique key of the published component set. | > | `team_id` | String | ID of the team whose library publishes the component set. | > | `file_key` | String | Key of the library file that contains the component set. | > | `node_id` | String | ID of the component set's node inside the library file. | > | `name` | String | Name of the component set. | > | `description` | String | Description written by the publisher. | > | `thumbnail_url` | String | Address of the thumbnail image (signed by Figma; stops working after a while). | > | `created_at` | Datetime | When the component set was created (UTC). | > | `updated_at` | Datetime | When the component set was last updated (UTC). | > | `user_id` | String | Figma user ID of the person who last updated it. | > | `user_handle` | String | Name of the person who last updated it. | > | `user_img_url` | String | Profile picture of the person who last updated it. | > | `page_id` | String | ID of the page of the library file that holds it. | > | `page_name` | String | Name of the page of the library file that holds it. | > | `frame_node_id` | String | ID of the frame that contains it, when there is one. | > | `frame_name` | String | Name of the frame that contains it, when there is one. | > | `component_set_node_id` | String | ID of the parent component set, when there is one. | > | `component_set_name` | String | Name of the parent component set, when there is one. | > | `containing_frame` | String (JSON) | Frame that contains it as Figma sends it (JSON object). | > [accordion] Styles > > Color (fill), text, effect and grid styles published to each team's library. Read in full on every sync. > > Table: `styles` · Primary key: `key` · Sync: Full table > > | Field | Type | Description | > | :- | :- | :- | > | `key` | String | Unique key of the published style, used to reference it across files. | > | `team_id` | String | ID of the team whose library publishes the style. | > | `file_key` | String | Key of the library file that contains the style. | > | `node_id` | String | ID of the style's node inside the library file. | > | `name` | String | Name of the style. | > | `description` | String | Description written by the publisher. | > | `thumbnail_url` | String | Address of the style's thumbnail image (signed by Figma; stops working after a while). | > | `created_at` | Datetime | When the style was created (UTC). | > | `updated_at` | Datetime | When the style was last updated (UTC). | > | `user_id` | String | Figma user ID of the person who last updated the style. | > | `user_handle` | String | Name of the person who last updated the style. | > | `user_img_url` | String | Profile picture of the person who last updated the style. | > | `style_type` | String | Kind of style: FILL (colors), TEXT, EFFECT or GRID. | > | `sort_position` | String | Position set by the publisher to order the styles. | ## Implementation Notes ### Data Quality Considerations * **Subfolders**: on teams that Figma only lists through its older project routes, subfolders are not available; the sync log warns when this happens. * **What the token can see is what you get.** The connector reads Figma as the person who generated the token: projects, files and libraries of the configured teams that this person can access. Files in personal Drafts are not part of any team and are not extracted. * **A full-table stream is never loaded by half**: every full-table stream is read completely before anything is loaded, so a sync that fails halfway leaves the previous table in place. If Projects, Files or File Metadata (or File Versions, when its sync type is Full table) come back completely empty after a sync that had records, that stream fails and its table is left as it was. * **File Versions**: the first sync and any full sync are all-or-nothing, like the full-table streams: if one is interrupted, the next sync reads everything again. Once a first sync has succeeded, incremental syncs are saved file by file, and an interrupted incremental sync continues from the files already read. Continuing from where it stopped applies only to these incremental syncs, never to the first sync or a full sync. * **Files deleted during a sync**: a file or project deleted between being listed and being read is left out of that sync with a warning in the sync log. A project is only treated as deleted after the connector checks it again. If too many disappear at once, that stream fails and its table is left as it was. * **File Versions** is incremental per file: a version renamed or re-described long after it was created is only updated by a full sync. On the **Starter** plan Figma keeps only 30 days of version history, so a full sync of File Versions on Starter replaces the table with the last 30 days only; prefer incremental syncs and avoid **Additional Full Sync** for this stream on Starter. * **File content is not extracted**: layers, frames, images and exports of the design files are not part of this connector. ### API Limits & Performance * Figma limits requests per token, per plan and per kind of request, every minute. Listing projects and files, versions and comments are limited to 5 requests per minute on the Starter plan, 25 on Professional, 50 on Organization and 100 on Enterprise; file metadata, components and styles to 10, 50, 100 and 150. A token generated by someone with a **View** or **Collab** seat gets much lower limits than a **Full** or **Dev** seat. See [Figma's rate limits](https://developers.figma.com/docs/rest-api/rate-limits/). * The connector reads one request at a time and, when Figma asks it to slow down, waits exactly as long as Figma says and then paces its requests to your plan's limit for the rest of the sync. The sync log shows when this happens and, for teams with many files, how many files were read and an estimate of the time left. * File Metadata, File Versions and File Comments need at least one request **per file** on every sync. As a reference, on a Professional plan a team with 1,000 files takes more than an hour for versions and comments. For large teams, select only the file streams you need, keep a Start Date for File Versions, and schedule the source accordingly. ## Troubleshooting | Error or symptom | What it means | What to do | | :- | :- | :- | | "Figma rejected the access token of this source" | The token is wrong, expired (after at most 90 days) or was revoked. | Generate a new token in Figma (**Settings > Security > Personal access tokens**) with the scopes above and update the source. | | "The Figma token of this source is not allowed to read ..." | The token is missing the scope that stream needs, or its user has no access to that team, project or file. | Generate a token with all the scopes listed above, by a member of the team, or deselect that stream. | | "The Figma token of this source is not allowed to list the folders of team ..." | The token was generated without the **Folders** read scope. | Generate a new token with all the scopes listed above and update the source. | | "Figma did not find team ..." or "Figma refused team ID ..." | The team ID is wrong, or the user who generated the token is not a member of that team. | Copy the number after `/team/` from the team page address and check the token's user is a member. | | "Figma returned no ... records at all, although the previous sync read N" | A stream that had records came back empty, so that stream was not loaded and its table was left as it was. | Check the token still has access to the teams. If the data really was removed in Figma, run a full sync of the source to accept the empty table; otherwise deselect that stream. | | "N files were deleted in Figma while this sync was running" | Files disappeared between being listed and being read. | No action needed; the next sync no longer sees them. | | "Figma does not provide the ... of N of M files through its API" | Figma refused that information for some files (for example a file type the endpoint does not support). | No action needed; those files are left out of that stream. | | "Figma is limiting how fast this token may read" | Figma's rate limit was reached; the connector is waiting. | No action needed. If syncs are too slow, use a token of a user with a Full or Dev seat, deselect file streams you do not need, or run the source less often. | | "The Figma token of this source belongs to a user with a View or Collab seat" | Figma gives this seat very few requests per minute. | Use a token generated by a user with a Full or Dev seat. | | "Figma has used up the request budget of this token" | Figma asked to wait more than 30 minutes, so the sync stopped. | Run the source later, less often, or with a token of a Full or Dev seat. | | "Figma kept failing while reading ..." or "Figma did not answer ..." | The Figma API returned errors or timed out several times in a row. | Run the source again later. | | "Figma answered ... in a format this connector does not recognise" | The Figma API changed. | Contact Nekt support. | ## Skills for agents > [card] [Download Figma skills file](https://docs.nekt.com/sources/figma.md) > > Figma connector documentation as plain markdown, for use in AI agent contexts. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.