Skip to main content
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 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 and create one. A key can be scoped to the whole company (it reads every project) or to a single project.
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.
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, 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.
  • Determine when to execute an 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 page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your 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.
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

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.
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.
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.
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.
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).
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.
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).
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.
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.
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.
One row per project, day, bot, host and response status. Spoofed bot traffic is excluded.Fields: date, bot_id, request_host, response_status, visits.
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