> ## 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.

# Peec AI as a data source

> Bring AI search visibility data from Peec AI to your Lakehouse.

Peec AI is an AI search analytics platform. It asks AI assistants (ChatGPT, Perplexity, Google AI Overviews and others) the prompts you track, every day, and measures how often your brand and your competitors are mentioned, in which position, with which sentiment, and which websites the answers use as sources. This connector reads the Peec AI Customer API and brings your projects, brands, prompts, chats and the daily brand, domain, URL and link reports into your Lakehouse.

## Configuring Peec AI 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 Peec AI option from the list of connectors.

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

### 1. Add account access

You'll need a Peec AI API key. In Peec AI, open [API keys](https://app.peec.ai/api-keys) and create one. A key can be scoped to the whole company (it reads every project) or to a single project.

> [!WARNING]
>
> Access to the Peec AI API is available on the **Pro, Advanced, Enterprise and Agency** plans. Starter plans don't include API access, and the connection fails with them.

The following configurations are available:

* **API Key**: The Peec AI API key. A company-scoped key is recommended: the connector then lists your projects by itself.

* **Start Date**: The earliest day read by the daily tables (reports, chats and analytics) on the first sync and on a full sync.

* **Project IDs**: (Optional) The Peec AI projects to read. Project IDs start with `or_`. Leave it empty to read every project of a company-scoped key.

> [!NOTE]
>
> With a **project-scoped** key, the connector cannot list projects: enter the ID of the key's project in **Project IDs** (exactly one ID). Peec AI does not return the project ID with the data, so the connector cannot check it: the ID you enter is written in the `project_id` column of every row. Make sure it is the key's project.

* **Lookback Days**: (Default: 7) How many days before the last sync every sync reads again. Peec AI keeps updating recent days (late chats and metric recalculations), so the last days are always refreshed.

* **Chat Contents Start Date**: (Optional) The earliest day read by the `chat_contents` table, which makes one request per chat. When empty, the first sync and any Full sync read it from **Start Date**; a project added later to a source that already syncs starts with its 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.

> 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 recent days (from the last sync minus the lookback), which is how the report and chat tables are meant to run.
  * Full table: every time the extraction happens, we'll get the current state of the data, from **Start Date** on for the daily tables.

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. Peec AI collects new chats once a day, so a daily trigger is usually enough.

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. Every table has a `project_id` column with the Peec AI project the row belongs to.

| Stream | Slug | Sync | Description |
| - | - | - | - |
| Projects | `projects` | Full table | Projects of the company. Needs a company-scoped API key. |
| Brands | `brands` | Full table | Your brands and the competitors tracked in each project. |
| Prompts | `prompts` | Full table | Tracked prompts, active and archived, with topic and tags. |
| Tags | `tags` | Full table | Prompt tags, including Peec AI's system tags (branding and intent). |
| Tag Groups | `tag_groups` | Full table | User-defined tag groups. |
| Topics | `topics` | Full table | Prompt topics. |
| Model Channels | `model_channels` | Full table | AI surfaces tracked by the project (ChatGPT, Perplexity, Google AI Overviews...). |
| Agent Bots | `agent_bots` | Full table | AI crawler bots known to Peec AI Agent Analytics. |
| Chats | `chats` | Incremental (`date`) | Every AI answer collected: prompt, model channel and day. |
| Chat Contents | `chat_contents` | Incremental (`date`) | The full answer of each chat: text, sources, links, brands mentioned, search queries, products. One request per chat. |
| Brand Report | `brand_report` | Incremental (`date`) | Daily visibility, share of voice, win rate, sentiment and position per brand and model channel. |
| Brand Report by Prompt | `brand_report_by_prompt` | Incremental (`date`) | The brand report broken down by prompt too. |
| Domain Report | `domain_report` | Incremental (`date`) | Daily source domains retrieved and cited by AI answers, per model channel. |
| URL Report | `url_report` | Incremental (`date`) | Daily source URLs retrieved and cited by AI answers, per model channel. |
| Link Report | `link_report` | Incremental (`date`) | Daily domains the answers linked to in their own text, per model channel. |
| Agent Visits | `agent_visits` | Incremental (`date`) | Daily AI bot visits to your websites, per bot, host and response status. Needs Agent Analytics set up in Peec AI. |
| AI Referrals | `ai_referrals` | Incremental (`date`) | Daily website traffic referred by AI assistants, from the Google Analytics 4 property connected to the project. |

> [!NOTE]
>
> Ratios such as `visibility`, `share_of_voice`, `win_rate`, `citation_rate` and the percentages must not be summed or averaged across rows. Re-aggregate them from the count, sum and total columns (for example, visibility = `sum(visibility_count) / sum(visibility_total)`), as described in each field.

## Fields by stream

> [accordion] Projects
>
> **Fields:**
>
> * `id` - Unique identifier of the project.
> * `name` - Name of the project.
> * `status` - Lifecycle status of the project (CUSTOMER, TRIAL, PITCH, PAUSED, DELETED...).
> * `country_code` - Default country of the project's market.
> * `language_code` - Language the project's prompts run in.
> * `external_id` - External identifier set on the project.
> * `chat_interval_weekdays` - Weekdays the project runs its prompts (1 = Monday, 7 = Sunday); empty means daily.
> * `chat_interval_month_days` - Days of the month the project runs its prompts, when it runs on fixed month days.
> * `created_at` - Date the project was created.

> [accordion] Brands
>
> **Fields:**
>
> * `project_id`, `id` - Project and brand identifiers.
> * `name` - Name of the brand.
> * `domains` - Web domains that belong to the brand.
> * `aliases` - Alternative names also counted as a mention of the brand.
> * `regex` - Regular expression used to detect the brand, when set.
> * `is_own` - Whether it is one of your own brands (false for competitors).
> * `color` - Color of the brand in Peec AI charts.
> * `source` - How the brand was added: manual, suggestion or onboarding.

> [accordion] Prompts
>
> **Fields:**
>
> * `project_id`, `id` - Project and prompt identifiers.
> * `text` - Text of the prompt.
> * `messages` - Messages of the prompt (JSON).
> * `topic_id` - Topic of the prompt (a prompt has at most one topic).
> * `tag_ids` - Tags of the prompt (a prompt can have several tags).
> * `country_code` - Country the prompt is asked from.
> * `volume` - Estimated search volume of the prompt.
> * `is_archived` - Whether the prompt is archived (no longer tracked; its history is kept).
> * `created_at` - Date the prompt was created.

> [accordion] Tags, Tag Groups and Topics
>
> **Tags:** `project_id`, `id`, `name`, `is_system` (system tags are maintained by Peec AI), `group` (branding or intentType for system tags, the group name for user tags).
>
> **Tag Groups:** `project_id`, `group`, `color`, `tag_count`.
>
> **Topics:** `project_id`, `id`, `name`.

> [accordion] Model Channels and Agent Bots
>
> **Model Channels:** `project_id`, `id` (e.g. `openai-0`), `description`, `current_model_id`, `is_active`, `unsupported_country_codes`.
>
> **Agent Bots:** `project_id`, `id` (bot user agent name), `provider`, `type` (training, search, userQuery or other).

> [accordion] Chats
>
> **Fields:**
>
> * `project_id`, `id` - Project and chat identifiers.
> * `date` - Day the chat was collected (UTC), the incremental replication key.
> * `prompt_id` - Prompt that was asked.
> * `model_channel_id` - Model channel that answered.
> * `model_id` - Model that answered (deprecated by Peec AI in favor of `model_channel_id`).
> * `features` - Special elements in the answer: SHOPPING, PRODUCT\_COMPARISON, AD, MAP, WEB\_SEARCH, LINKS, CHART.

> [accordion] Chat Contents
>
> Every field of **Chats**, plus:
>
> * `messages` - The prompt and the AI answer, each with role and content (JSON).
> * `sources` - Sources the answer retrieved, with URL, domain, citation count and citation position (JSON).
> * `links` - URLs the answer wrote into its own text (JSON).
> * `brands_mentioned` - Brands mentioned in the answer, with their position (JSON).
> * `queries` - Search (fan-out) queries the model ran to answer.
> * `products` - Shopping products shown in the answer (JSON).
> * `maps` - Local-business map cards (JSON).
> * `ads` - Paid ad placements (JSON).

> [accordion] Brand Report and Brand Report by Prompt
>
> One row per project, day, brand and model channel (and prompt, in **Brand Report by Prompt**).
>
> **Fields:**
>
> * `date`, `brand_id`, `brand_name`, `model_channel_id` (and `prompt_id`).
> * `visibility` - Share of chats in which the brand was mentioned (`visibility_count / visibility_total`).
> * `visibility_count`, `visibility_total` - Chats with a mention, and chats in scope.
> * `mention_count` - Number of mentions of the brand.
> * `share_of_voice` - Brand mentions divided by the mentions of every brand in the same row grouping.
> * `win_rate`, `win_count` - Share and number of chats in which the brand was named first.
> * `sentiment`, `sentiment_sum`, `sentiment_count` - Average sentiment (0-100), re-aggregated as `((sum(sentiment_sum) / sum(sentiment_count)) / 2 + 0.5) * 100`.
> * `position`, `position_sum`, `position_count` - Average position among the brands named (1 = first), re-aggregated as `sum(position_sum) / sum(position_count)`.
>
> Join `brand_report_by_prompt` with `prompts` on `prompt_id` to analyze by topic or tag. A prompt can have several tags, so do not add tag-level results together to get a total.

> [accordion] Domain Report
>
> One row per project, day, domain and model channel.
>
> **Fields:**
>
> * `date`, `domain`, `model_channel_id`, `classification` (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED or a custom classification).
> * `retrieved_percentage`, `cited_percentage` - Share of chats that retrieved, or cited inline, at least one URL of the domain.
> * `retrieval_rate`, `citation_rate` - Retrievals per chat in scope, and inline citations per chat that retrieved the domain.
> * `retrieval_count`, `citation_count`, `retrieved_chat_count`, `cited_chat_count`, `total_chat_count` - The counts behind the rates.
> * `mentioned_brand_ids` - Brands mentioned alongside URLs of the domain.

> [accordion] URL Report
>
> One row per project, day, URL and model channel.
>
> **Fields:**
>
> * `date`, `url`, `model_channel_id`, `classification` (HOMEPAGE, CATEGORY\_PAGE, PRODUCT\_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW\_TO\_GUIDE, ARTICLE, REVIEW, OTHER or a custom one), `title`, `channel_title`.
> * `retrieval_count`, `citation_count`, `citation_rate` - Chats that retrieved the URL, inline citations, and citations per retrieval.
> * `citation_position`, `citation_position_sum`, `citation_position_count` - Average rank among the sources cited inline (1 = first).
> * `mentioned_brand_ids` - Brands mentioned alongside the URL.

> [accordion] Link Report
>
> One row per project, day, domain and model channel, for the links the answers wrote into their own text (never the sources, which are in the domain report).
>
> **Fields:**
>
> * `date`, `domain`, `model_channel_id`, `classification`.
> * `linked_chat_count`, `linked_percentage`, `link_count`, `average_link_position`, `total_chat_count`.

> [accordion] Agent Visits
>
> One row per project, day, bot, host and response status. Spoofed bot traffic is excluded.
>
> **Fields:** `date`, `bot_id`, `request_host`, `response_status`, `visits`.

> [accordion] AI Referrals
>
> One row per project, day, AI assistant, host and landing page, from the Google Analytics 4 property connected to the project in Peec AI.
>
> **Fields:**
>
> * `date`, `assistant` (`(not set)` when unknown), `host`, `landing_page`.
> * `events` - GA4 event count.
> * `session_starts` - GA4 `session_start` events (not GA4's sessions metric).
> * `conversions` - GA4 key events.
> * `revenue`, `currency` - GA4 purchase revenue in the property's reporting currency.

## Implementation Notes

### Data freshness and history

* Each project keeps its own sync position. Every sync reads again the last **Lookback Days** before it, because Peec AI keeps updating recent days. This includes `chat_contents`, so chats collected late also get their contents.
* When a table cannot be read for some projects (missing access or plan), the whole table is reported as not updated in that run and its sync position is kept, so the next successful run reads the same days again. While the access stays missing, every run re-reads a longer period for all projects: fix the access, deselect the table, or remove those projects from **Project IDs**.
* A **Full Sync** reads the daily tables again from **Start Date** (and `chat_contents` from **Chat Contents Start Date** when set), then replaces the tables. For `chat_contents` this means one request per chat over that whole period.
* Peec AI recalculates a brand's metrics for its whole history when you edit its name, aliases or regular expression, and deleting a prompt deletes its chats. Run a **Full Sync** after such changes to refresh older days.
* Chats of archived prompts are included, so their history stays in your tables.

### API Limits & Performance

* Peec AI allows 200 requests per minute per project. The connector paces its requests and waits when the limit is reached.
* `chat_contents` makes one request per chat. On a project with many prompts and model channels, a long history can take hours: set **Chat Contents Start Date** to a recent date if you don't need old answers. Each run also reads the **Lookback Days** again, one request per chat.
* `brand_report_by_prompt` and `url_report` can be large on projects with many prompts or sources; select them only if you need that detail.

## Troubleshooting

| Error or symptom | What it means | What to do |
| :- | :- | :- |
| "Peec AI rejected the API key" | The key is wrong, revoked, or missing. | Create a new key in Peec AI and update the source. |
| "A project-scoped API key cannot list the company's projects" | The key belongs to a single project. | Enter that project's ID in **Project IDs**, or use a company-scoped key. |
| "The Peec AI plan does not include this data" | The plan has no API access, or not for that feature. | API access needs a Pro, Advanced, Enterprise or Agency plan. |
| A table was not updated, naming some projects | The key or plan has no access to that data for those projects. The other tables still sync; the table is read again on the next run. | Give the key access in Peec AI, deselect the table, or limit **Project IDs**. |
| `ai_referrals` has no data for a project | Google Analytics 4 is not connected to that project in Peec AI. The other projects sync normally. | Connect GA4 to the project in Peec AI. |
| "One day of a table has more rows than Peec AI serves in one request" | A single day of that report is larger than one API page, even per model channel. | Contact support with the source slug and the run ID. |
| `projects` was not updated | The API key is project-scoped. | Use a company-scoped key, or deselect `projects`. |


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