Getting started with SQL in Composer and the Klaviyo MCP server

You will learn

Learn how to ask analytics questions about your Klaviyo data in plain language using Composer or the Klaviyo Model Context Protocol (MCP) server. Klaviyo Data Platform SQL brings together profiles, audiences, campaigns, products, and events to answer questions that involve multiple data sets. You don't need to write SQL.

SQL is currently in beta and is available to all customers.

Before you begin

Choose where you want to ask your questions:

• Use Composer to work in the chat inside Klaviyo. There's no additional SQL setup.
• Use the Klaviyo MCP server to work in a connected AI client, such as Claude or ChatGPT. If you've already connected Klaviyo, you don't need to install another tool, although you may need to refresh the client's tool list.

Both options use the same data and support the same kinds of analytics questions. SQL is designed for analysis. For bulk data exports, use other Klaviyo tools, such as custom reports.

Data is typically about 30 minutes behind activity in your account. For a very recent order, send, or membership change, check directly in Klaviyo.

Ask your first analytics question

Use Composer

1. Open Composer in Klaviyo. If you need help finding it, see Getting started with Composer.
2. Ask an analytics question in plain language. Include the metric, date range, and any audience or product details. For example, “What are my top 5 products by units sold in the last 90 days?”
3. Review the answer, then ask follow-up questions in the same conversation to explore it further.

Composer decides when to use SQL. You don't need to name a tool or change a setting.

Use the Klaviyo MCP server

To connect an AI client, you need an Owner, Admin, or Manager role in the Klaviyo account you want to use. When your connection uses an API key, the key needs access to the data sets involved in your question. For example, a question about orders and segments needs access to events and segments.

1. Connect Klaviyo using the guide for your client or setup:
   • Klaviyo MCP server developer documentation for terminal and remote-server connections
   • Klaviyo app for Claude FAQ
   • How to use the Klaviyo app for ChatGPT
   • Klaviyo MCP server guide for agencies for working across client accounts
2. Ask a detailed analytics question in your connected client. You don't need to name the ask_analytics_question tool. Your client selects it when appropriate for the question.
3. Review the answer and continue with follow-up questions. If the tool isn't available, refresh your client's Klaviyo tool list using the troubleshooting steps below.

If you connect through OAuth, follow your client's guide to review and grant the requested permissions.

Build on an answer and check the calculation

SQL is useful when a question needs information from multiple data sets. For example, a count of orders becomes a more detailed audience analysis when you add customers, segment membership, and country.

Start with a question, then build on the answer in the same conversation:

1. “How many orders did we take last month?”
2. “How many customers placed those orders?”
3. “Break those orders down by the segments the customers currently belong to.”
4. “Break the results down by segment and country, and include revenue for each group.”
5. “For first-time buyers, how much product browsing happened in the 10 days before their first order?”

Ask how the answer was calculated before sharing an important number or using it to make a decision. For example:

• “Which data sets did you use?”
• “What date range and filters did you apply?”
• “How did you define revenue in this calculation?”
• “Walk me through how you calculated that.”

Use the explanation to check that the answer matches your intended question. If it doesn't, clarify the metric, dates, or filters and ask again.

What data you can ask about

SQL can answer questions about these data sets, subject to the permissions on your connection.

Events and details within events

Available event data includes:

• Commerce activity, such as adding to a cart, placing or canceling an order, refunds, and product views
• Email activity, including receives, opens, clicks, bounces, drops, and unsubscribes
• SMS and WhatsApp activity, including receives, clicks, failures, consent, and unsubscribes
• Push activity, including receives, opens, and bounces
• Consent and suppression changes, including subscriptions, unsubscribes, suppression additions or removals, and preference updates
• Flow activity, including entries, removals, fulfillment, skips, and starts
• Profile merges
• Review and rating submissions, edits, deletions, and readiness to review
• Coupon assignments and uses
• Support conversation activity, including starts, received or sent messages, escalations, resolutions, and ticket creation or closure
• Customer Hub activity, such as logins, favorites, product or coupon clicks, and content block views
• Integration events from sources such as your API, Shopify, and Lightspeed, including checkout activity, form submissions, loyalty signups, searches, and shipments
• Marketing metrics, including delivery, recipient, open, click, bounce, unsubscribe, spam complaint, and human engagement counts and rates

Some events contain nested values: groups of related details within an event. For example, an order can contain a list of items, each with a SKU, quantity, and price. SQL can read those details, so you can ask how many orders included a particular SKU or what the average number of items per order was.

Combine data sets

SQL can connect related data sets to answer a question. This is called a join, but you don't need to request a join explicitly. For example, you can:

• Connect campaign messages to campaign names and engagement data to compare named campaigns.
• Connect current list or segment membership to profiles and orders to analyze an audience's purchase activity.
• Break down an audience by country, consent status, or predicted customer value.
• Connect products to categories, or variants to parent products, to analyze product or category performance.
• Connect coupon assignments to coupon uses to calculate redemption and identify unredeemed coupons.

Example questions

Adapt the dates, products, segments, and campaign details to your account.

Understand the limits

Unavailable data

SQL doesn't currently support:

• List or segment membership at a past point in time
• Signup forms or their performance
• Custom objects
• Email or SMS templates

Integration events can include form submissions, but that doesn't mean SQL supports analysis of signup forms or their performance. If your question depends on unavailable data, the answer may be incomplete or the client may be unable to answer.

Data freshness and differences from Klaviyo reports

Data is typically about 30 minutes behind your account. Recent activity may not appear immediately.

Numbers should generally be consistent with Klaviyo, but small differences can occur because of differences in definitions, query optimizations, or data freshness. SQL uses a different data source from other ways of accessing Klaviyo data. Klaviyo has checked this data to be 99% consistent over the past 3 years.

Ask for the calculation, date range, and filters when a number differs from a report. The explanation can help you identify whether you're comparing the same metric and period.

Generated queries and timeouts

SQL generates a query from your question. There isn't currently an endpoint where you can submit your own SQL query and receive a guaranteed, repeatable result. Different wording can produce different queries and slightly different results. Check the calculation for important numbers.

An MCP client can stop waiting for a response sooner than Composer would. Claude, for example, has a 60-second timeout window. If a question times out, narrow the date range, reduce the number of breakdowns, or split the analysis into smaller questions.

Troubleshooting

The analytics tool isn't available

If you don't see ask_analytics_question in your AI client, confirm that SQL is enabled for your account and refresh the client's Klaviyo tool list.

In Claude:

1. Go to Customize > Connectors > Klaviyo.
2. Open the three-dot menu in the upper right-hand corner.
3. Click Refresh tool list, then try your question again.

SQL can't return data you know is in your account

Check whether the data set is supported and allow for the typical 30-minute delay. If your connection uses an API key, check that it has access to every data set involved, such as profiles, segments, lists, campaigns, catalogs, or events. Update missing permissions in Klaviyo, refresh the client's Klaviyo tool list, and retry the question.

For an OAuth connection, review the permissions using your client's connection guide.

A question times out

Try a shorter date range or fewer breakdowns, or split the question into smaller questions. Retry the narrower question, then build on the result with follow-ups.

A number doesn't match Klaviyo

Ask how SQL calculated the number, including the data sets, date range, and filters. Check whether the metric definitions and data freshness explain the difference. If the difference is large, contact Klaviyo Support and share the question, the returned number, and the number you expected.

Composer declines a question

Rephrase the question with a specific metric, date range, and audience. Check that it uses one of the supported data sets, then retry.

Additional resources

• Getting started with Composer
• Klaviyo MCP server developer documentation
• Klaviyo app for Claude FAQ
• How to use the Klaviyo app for ChatGPT
• Klaviyo MCP server guide for agencies
• Getting started with custom reports in Klaviyo