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. 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_contentstable, 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.
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.
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.
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.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 aproject_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
Projects
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.
Brands
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.
Prompts
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.
Model Channels and Agent Bots
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).Chats
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 ofmodel_channel_id).features- Special elements in the answer: SHOPPING, PRODUCT_COMPARISON, AD, MAP, WEB_SEARCH, LINKS, CHART.
Chat Contents
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).
Brand Report and Brand Report by Prompt
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(andprompt_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 assum(position_sum) / sum(position_count).
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.Domain Report
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.
URL Report
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.
Link Report
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.
Agent Visits
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.AI Referrals
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- GA4session_startevents (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_contentsfrom Chat Contents Start Date when set), then replaces the tables. Forchat_contentsthis 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_contentsmakes 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_promptandurl_reportcan be large on projects with many prompts or sources; select them only if you need that detail.