Skip to main content
This page takes an AI agent from no Tolstoy account to reading the analytics events of the store that it builds, using the E-commerce Analytics SDK (the TolstoySDK package). It also says what Tolstoy measures and what it does not, so that you can tell your client before you start. This page as Markdown: https://developers.gotolstoy.com/agents/ecommerce-analytics.md. All pages: https://developers.gotolstoy.com/llms.txt. If you are a person, give your agent this prompt:

What you get

Your storefront code sends events with the E-commerce Analytics SDK, for example product_view, add_to_cart or checkout_started. You choose the names. For any period of whole UTC days, up to 180 days, the Tolstoy store analytics report gives each event name with two numbers:
  • events: how many times the event was sent.
  • shoppers: how many different shoppers sent it. The SDK keeps one shopper ID per browser, so one person on two devices counts as two shoppers.
Sending events and reading the report are free on every Tolstoy plan, the free plan included. Your events never count toward Shoppable Videos view billing. You do not need a Tolstoy widget on the store. Tolstoy also makes shoppable video, try-on and chat widgets, and AI images and videos for e-commerce brands; the SDK and the report work without them.

What you do not get

  • No conversion rate, funnel or revenue for your events, and no orders beyond the count of an order event that you send yourself. The report counts each event name on its own, and it does not link your events to orders.
  • No numbers by parameter. Tolstoy keeps the parameters of each event, but the report does not show them or group by them.
  • No numbers for today. The report covers whole UTC days before today. Events that you send today show in the report from about 06:30 UTC tomorrow.
  • No daily series. For the counts of one day, ask for a period of that one day.
  • No server SDK. The SDK runs in the browser, on the storefront page. It has no call that identifies a shopper by email or account.
  • Up to 120 event names in one report, the most frequent first. The list also holds the events of Tolstoy widgets, if the store has any.

What needs a browser

Two steps run on Tolstoy pages in a browser, not through an API:
  1. Sign-up. It uses a Google account, or an email address and a password with a 6-digit code that Tolstoy sends to that address. You need a browser and access to that inbox.
  2. The approval of the sign-in of the Tolstoy CLI or the Tolstoy MCP, on the page that the sign-in opens.
If you cannot use a browser or read the inbox, ask the person that you work for to do these steps.

1. Create the account and sign in

With the Tolstoy CLI:
tolstoy auth signup opens the Tolstoy sign-up page in the browser, and prints its link in case the browser does not open. After sign-up, the browser goes to the CLI sign-in page. Click Sign in there, and the CLI saves its key. If the account already exists, run tolstoy auth login instead. tolstoy auth status shows the account, app key and store that the CLI uses. With the Tolstoy MCP, sign up at https://platform.gotolstoy.com/signup. Then add the server https://apilb.gotolstoy.com/mcp/v1/mcp to your MCP client, and sign in to Tolstoy when the client asks. Connect your agent has the command for each client.

2. Get the app key

The app key identifies the Tolstoy workspace. It is not a secret: it is in the code of every page that sends events.
  • With the CLI, copy the App key: value printed by tolstoy auth signup, tolstoy auth login or tolstoy auth status. Use it as the SDK’s appKey, not the secret API key on the Key: line.
  • With the MCP, list_workspaces returns the app key as currentAppKey.
  • In Tolstoy, go to Settings → API, MCP & CLI → API, and copy App Key (https://platform.gotolstoy.com/settings/api-keys). The key is there on every plan, with no widget.

3. Send events

The E-commerce Analytics SDK is an ES module on the Tolstoy CDN. Create one SDK on the page, and call track() for each event:
Tolstoy records each event as tolstoy-sdk.<name>, for example tolstoy-sdk.add_to_cart. Parameters are strings, numbers and booleans. The Tolstoy SDK page has the limits of names and parameters. The SDK sends no event until the shopper allows analytics, and it drops the events from before that. If the store has a consent banner, set tolstoy-cookie-policy in localStorage to accepted or rejected from its answer, before the first event. With no consent tool on the page and no stored value, the SDK sends the events. Shopper consent has the code for Shopify.

5. Confirm delivery today

The report does not show today’s events, so check the requests. The SDK sends each event as one POST request to https://analytics-v2.gotolstoy.com/event. It sends the queued events every 10 seconds, when 10 events are in the queue, and when the shopper leaves the page.
  • HTTP 200: Tolstoy received the event. The body of the request holds eventName (tolstoy-sdk.<name>) and appKey. Check that both are right.
  • No request: the shopper’s consent blocks analytics, or the next batch has not been sent yet. Wait 10 seconds, or leave the page.
To see the requests, open the network log of the browser, or record the requests with a browser automation tool such as Playwright. On the day that you send, HTTP 200 is the only check. The report shows the counts the next day.

6. Read your events

From about 06:30 UTC on the next day, ask for the report of the day that you sent the events:
In the JSON, events lists each event name with its widget type, the number of events and the number of shoppers. Your events have the widget type tolstoy-sdk and the name tolstoy-sdk.<name>.
  • The period is whole UTC days, up to 180 days. A period that reaches today stops at the end of yesterday.
  • --app-url selects a store from tolstoy stores list. Without it, the CLI uses the store that it saved at sign-in. scope.appUrl in the report names the store that the report read, and stores lists all the stores of the workspace.
With the MCP, call get_store_analytics with dateFrom, dateTo and sections: ["details"]. It returns the same report.

Tools for your agent

  • Skills. npx skills@latest add https://developers.gotolstoy.com --skill ecommerce-analytics installs the ecommerce-analytics skill into the project. It tells an agent what to measure in a store, which events to send, how to work out rates from the counts of the report, and how to judge a number against benchmarks per vertical from Tolstoy’s store data. npx skills@latest add https://developers.gotolstoy.com --skill store-analytics installs the store-analytics skill, which tells an agent how to read the report and what each number means.
  • Project note. Add a note to the AGENTS.md file of the store’s project: the store sends its events with the Tolstoy SDK, and tolstoy analytics get-store-analytics reads their counts. The next agent on the project then finds them.
  • Reference. Tolstoy SDK for the SDK, Tolstoy CLI for the CLI, and Connect your agent for the MCP.