Skip to main content
The AI Chat feature lets you ask questions about your DATALYR data in natural language. It queries your analytics, attribution, events, users, and ad performance data to answer questions and generate insights.

​
What It Does

  • Query traffic, conversions, and revenue data by asking questions
  • Get attribution breakdowns by source, campaign, or ad
  • Look up individual user journeys and conversion paths
  • Query ad platform performance across Meta, Google, and TikTok
  • Check real-time visitor data and live metrics
  • View workspace usage and billing information
AI Chat uses the same Public API endpoints available to all API consumers. It does not have access to any data beyond what the API provides.

​
Setup

​
Generate an Agent Key

  1. Go to Settings -> API Keys in DATALYR
  2. Click “Generate Agent Key”
  3. Copy the key (starts with dk_agent_)
  4. The AI Chat panel is available in your dashboard sidebar
The Agent Key is required for AI Chat to function. Without it, the chat panel appears but cannot query your data. Both SDK keys (dk_) and Agent keys (dk_agent_) work on all API routes, but the Agent key is specifically designed for AI Chat.

​
Key Types

Key TypePrefixPurpose
SDK Keydk_Event ingestion, SDK setup, API access
Agent Keydk_agent_AI Chat, API access, MCP integrations
Both key types authenticate against all /api/v1/ endpoints with the same rate limits.

​
What You Can Ask

​
Traffic and Overview

Ask about visitors, pageviews, sessions, and general site metrics.
  • “How many visitors did we get this week?”
  • “What are the top traffic sources for the last 30 days?”
  • “Show me pageview trends for this month”
  • “Compare this week’s visitors to last week”
  • “What’s our bounce rate today?”

​
Attribution

Ask about marketing attribution and conversion sources.
  • “Which campaigns drove the most conversions?”
  • “What’s the attribution breakdown for purchases?”
  • “Show me revenue by UTM source”
  • “What campaign had the highest conversion rate this month?”
  • “Break down conversions by source and medium”

​
Users

Look up individual users or search for visitors.
  • “Look up user [email protected]”
  • “Show me the journey for user_123”
  • “How many sessions did [email protected] have?”
  • “What pages did visitor v_abc123 view?”
  • “Find users who converted this week”

​
Ad Performance

Query data from connected ad platforms (Meta, Google, TikTok).
  • “How are our Meta campaigns performing?”
  • “What’s the ROAS for Google Ads this week?”
  • “Compare TikTok vs Meta spend and conversions”
  • “Which ad has the lowest CPA?”
  • “Show me spend by platform for the last 30 days”
  • “What’s our overall ROAS across all platforms?”

​
Events

Query specific events and conversion data.
  • “What events fired today?”
  • “Show me all purchase events this week”
  • “How many signups did we get from Google?”
  • “List the event types we track”
  • “Show me events from the pricing page”

​
Real-Time Data

Check what is happening on your site right now.
  • “How many people are on the site right now?”
  • “What pages are visitors viewing?”
  • “Show me real-time visitor data”
  • “What are the top pages in the last 30 minutes?”

​
Workspace and Billing

Check workspace configuration and usage.
  • “What integrations are connected?”
  • “How many events have we used this month?”
  • “What plan are we on?”
  • “Show me our usage stats”

​
Example Conversations

​
Campaign Performance Review

You: What campaigns drove the most revenue this month?

AI: Here are the top campaigns by revenue for March 2026:

1. spring_sale (google/cpc) - $8,900 revenue, 45 conversions, 3.75% CVR
2. retargeting_q1 (facebook/paid) - $5,600 revenue, 32 conversions, 4.0% CVR
3. brand_search (google/cpc) - $3,200 revenue, 28 conversions, 5.1% CVR

Total revenue across all campaigns: $22,400

You: What's the ROAS for the spring_sale campaign?

AI: The spring_sale campaign (google/cpc) ROAS for March 2026:

- Spend: $1,200.50
- Revenue: $8,900.00
- ROAS: 7.41x

For every $1 spent, this campaign generated $7.41 in revenue.

You: Compare that to last month

AI: spring_sale campaign comparison:

February 2026:
- Spend: $980.00, Revenue: $6,200.00, ROAS: 6.33x, Conversions: 31

March 2026:
- Spend: $1,200.50, Revenue: $8,900.00, ROAS: 7.41x, Conversions: 45

ROAS improved by 17% month-over-month. Conversions increased by 45%.

​
User Lookup

You: Look up [email protected]

AI: Found user: [email protected] (user ID: u_def456)

- First seen: March 10, 2026
- Last seen: March 16, 2026
- Total events: 45
- Total sessions: 8
- Location: Austin, US
- Device: Desktop, Chrome

Conversions:
- purchase ($99.00) on March 14, 2026

You: Show me their journey

AI: Session history for [email protected]:

Session 1 (March 10):
- Pageview: / (from google.com, utm_source=google)
- Pageview: /pricing
- Pageview: /features

Session 2 (March 12):
- Pageview: /pricing (direct)
- Pageview: /signup
- Event: signup

Session 3 (March 14):
- Pageview: /dashboard (direct)
- Event: purchase ($99.00)

​
Real-Time Monitoring

You: How many people are on the site right now?

AI: Current real-time stats (last 30 minutes):

- Active visitors: 23
- Pageviews: 156
- Events: 42
- Revenue: $450.00

Top pages:
1. /pricing (12 visitors)
2. / (8 visitors)
3. /features (6 visitors)

Top referrers:
1. google.com (15 visitors)
2. direct (8 visitors)

​
How It Works

AI Chat uses the DATALYR Public API to fetch data. When you ask a question:
  1. The AI interprets your question and determines which API endpoints to call
  2. It constructs the appropriate API requests with date ranges, filters, and parameters
  3. It calls one or more /api/v1/ endpoints using your workspace’s Agent key
  4. It processes the response data and generates a natural language answer

​
Available Data Sources

The AI Chat has access to 14 API endpoints:
EndpointData
/api/v1/overviewVisitors, pageviews, sessions, custom events over time
/api/v1/trafficTraffic sources, campaigns, top pages
/api/v1/devicesBrowser, OS, device type breakdown
/api/v1/locationsGeographic breakdown (country, region, city)
/api/v1/eventsRaw event listing with filters
/api/v1/event-namesAll tracked event types
/api/v1/realtimeLive visitors and real-time metrics
/api/v1/attributionCampaign attribution and conversion data
/api/v1/usersUser listing and search
/api/v1/users/:idSingle user profile with journey
/api/v1/adsAd platform performance (Meta, Google, TikTok)
/api/v1/tagsTag analytics
/api/v1/workspaceWorkspace metadata and integrations
/api/v1/usageBilling period usage stats

​
Authentication

AI Chat authenticates using the same mechanism as external API consumers. Your workspace’s Agent key is encrypted at rest (AES-256-GCM) and decrypted only when the chat sends API requests. The chat goes through the same authentication, authorization, and rate limiting as any API call.

​
Billing

AI Chat messages count toward your plan limits. Each message you send (not each API call the AI makes) counts as one message.
PlanMessages per Month
Starter50
Growth500
Scale5,000
Messages reset on your billing date each month.
If you reach your message limit, the chat returns an error. Upgrade your plan in Settings -> Billing to increase your limit.

​
What Counts as a Message

  • Each question you send counts as one message
  • Follow-up questions in the same conversation each count as one message
  • The AI’s response does not count as a message
  • Failed responses (e.g., from rate limiting) do not count

​
Conversations

AI Chat saves your conversation history so you can return to previous questions.

​
Managing Conversations

  • New conversation: Click the “New Chat” button in the chat panel
  • View history: Previous conversations appear in the chat sidebar
  • Delete conversation: Click the delete button next to any conversation
  • Continue conversation: Click any previous conversation to resume it
Conversations are scoped to your user account within the workspace. Other team members cannot see your chat history.

​
Tips for Effective Questions

​
Be Specific About Time Ranges

The AI defaults to reasonable time ranges, but you get more accurate results by specifying dates. Less specific: “How are we doing?” More specific: “What’s our visitor count and conversion rate for the last 7 days compared to the previous 7 days?”

​
Name Exact Metrics

Use specific metric names to get precise data. Less specific: “How are our ads performing?” More specific: “What’s the ROAS and CPA for our Meta campaigns this month?”

​
Use Exact Event Names

If you know your event names, use them directly. Less specific: “Show me conversions” More specific: “Show me all purchase events this week filtered by utm_source=google”

​
Ask Follow-Up Questions

The AI maintains context within a conversation. Ask follow-up questions to drill deeper.
  1. “What are the top traffic sources this month?”
  2. “Break down the Google traffic by campaign”
  3. “What’s the conversion rate for the spring_sale campaign?”

​
Limitations

  • AI Chat has read-only access. It cannot modify settings, create conversion rules, or change configurations.
  • Data is limited to what the Public API provides. It cannot access raw database tables or internal metrics.
  • Rate limiting applies. The AI’s API calls count against the same 100 requests per minute limit as external API consumers.
  • Complex cross-referencing queries may require multiple questions. The AI calls API endpoints sequentially.
  • The AI does not have access to historical data beyond what your plan retains.

​
Troubleshooting

​
”Agent key not configured”

Generate an Agent key in Settings -> API Keys. The AI Chat requires a dk_agent_ key to function.

​
Slow Responses

The AI may make multiple API calls to answer complex questions. Each call processes real analytics data. Broad date ranges or high-cardinality queries take longer.

​
Incorrect or Incomplete Data

  • Verify the date range in the AI’s response matches your question
  • Check that relevant integrations are connected (Settings -> Connections)
  • For ad performance data, ensure Meta/Google/TikTok accounts are synced

​
Rate Limit Errors

If you or other API consumers have exhausted the 100 requests per minute limit, the AI receives rate limit errors. Wait and try again.

​
Message Limit Reached

If you see a message limit error, you have used all AI Chat messages for the current billing period. Check your usage in Settings -> Billing. Messages reset on your billing date.

​
Data Privacy

​
What the AI Can Access

AI Chat accesses only the data returned by the DATALYR Public API:
  • Aggregated analytics (visitor counts, pageview totals, conversion rates)
  • Traffic source breakdowns (referrers, UTM parameters)
  • Event listings (event names, timestamps, page paths)
  • User profiles (visitor IDs, user IDs, email addresses, session history)
  • Ad platform metrics (spend, impressions, clicks, ROAS)
  • Workspace configuration (plan, integrations, timezone)

​
What the AI Cannot Access

  • Raw database tables or internal system data
  • Other workspaces (all queries are scoped to your workspace)
  • Billing payment methods or financial account details
  • API keys or authentication credentials
  • Data from other DATALYR users in your workspace

​
Conversation Storage

Chat conversations are stored in your workspace database. Each conversation is scoped to the individual user who created it (via row-level security). Other team members in the same workspace cannot access your conversations. You can delete any conversation from the chat sidebar.

​
Third-Party Data Processing

AI Chat uses Claude (by Anthropic) to process your questions and generate responses. Your analytics data is sent to the AI model as context when answering questions. Anthropic does not use this data for model training.

​
Next Steps

Public API

Access the same endpoints programmatically

Dashboard

View your analytics visually

Customer Journeys

Explore individual user paths

Ad Reports

Deep dive into ad platform data