---
name: "analytics_track"
area: "analytics"
title: "Track events from outside the site"
price: "free"
method: "POST"
url: "https://api.conecto.chat/v1/tools/analytics_track"
mcp_server: "https://api.conecto.chat/mcp/analytics"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/analytics/analytics_track"
---

# Track events from outside the site (`analytics_track`)

Records events that happen away from the site, like orders, deals won or renewals, tied to the visit that led to them when it can be found.

Record what happened away from the site's pages: a Shopify order, a deal won, a call that booked a demo, a renewal. Up to 100 at once, each with props and revenue. An event joins the visit that led to it when you give the visitor's IP address and user agent (a Shopify order carries both; they find the visit and are never kept), or the email or contact of a person whose first visit Conecto kept; otherwise it counts without a source. Then analytics_breakdown shows which channels and campaigns bring the money. Don't track what the site itself already sends, or it counts twice. Free; each event counts toward the site's monthly events.

Price: Free. A call that fails costs nothing.

## Use it when

Something worth counting happened outside the website: a Shopify order, a deal won, a call that booked a demo.

- For something that happens on the site's own pages, use [analytics_define_events](https://conecto.chat/tools/analytics/analytics_define_events.md).

## Say this to your agent

> The Alder Street Hotel ordered 8 guest bikes for $9,400. Count it as a won deal and credit the campaign that brought them.

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `site` | string | yes | The site's domain (e.g. halversoncycle.example) or its site_id. 4 to 253 characters. |  |  |
| `events` | array of objects | yes | 1 to 100 items. |  |  |
| `events[].name` | string | yes, in each item of `events` | Up to 60 characters. |  |  |
| `events[].props` | object | no | Up to 10 plain values, like {"plan": "pro"}. |  |  |
| `events[].revenue` | number or string | no | The money it brought, like 129.90. |  |  |
| `events[].currency` | string | no | Exactly 3 characters. |  |  |
| `events[].at` | string | no | When it happened, with its offset; now if left out. Up to 40 characters. |  |  |
| `events[].visitor` | object | no | The IP address and user agent the order or form came from, as Shopify and most forms record them: to find the visit that led to it. Used once, never kept. |  |  |
| `events[].visitor.ip` | string | no | Up to 45 characters. |  |  |
| `events[].visitor.user_agent` | string | no | Up to 500 characters. |  |  |
| `events[].email` | string | no | A person whose first visit Conecto kept: the event is credited to it. Up to 254 characters. |  |  |
| `events[].contact_id` | integer | no | The same, by CRM contact. |  |  |
| `events[].page` | string | no | Where it happened, like /checkout. Up to 500 characters. |  |  |

## Example

Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon.

MCP: call `analytics_track` on the MCP server `https://api.conecto.chat/mcp/analytics` with these arguments:

```json
{
  "site": "halversoncycle.example",
  "events": [
    {
      "name": "Deal won",
      "email": "events@alderstreethotel.example",
      "revenue": 9400,
      "currency": "USD",
      "props": {
        "pipeline": "Fleet"
      }
    }
  ]
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/analytics_track \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site": "halversoncycle.example", "events": [{"name": "Deal won", "email": "events@alderstreethotel.example", "revenue": 9400, "currency": "USD", "props": {"pipeline": "Fleet"}}]}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "analytics_track",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "site": "halversoncycle.example",
    "events": [
      {
        "event": "Deal won",
        "stored": true,
        "tied_to": "contact",
        "source": "Google",
        "channel": "Organic search",
        "campaign": null
      }
    ],
    "stored": 1
  }
}
```

`result`: Each event with whether it was stored and what it was tied to (the visit, the contact's first visit, or nothing), with its source, channel and campaign; stored: how many were kept.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `not_found` | 404 | No site the business counts has that domain or site_id. | Call analytics_list_sites and use a domain from it. |
| `invalid_input` | 400 | An event has no name, an IP address that is not one, a time outside the last 30 days or revenue without a currency, or there are more than 100. | Fix the event the message names. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [analytics_add_site](https://conecto.chat/tools/analytics/analytics_add_site.md): Starts counting visits to a website, without cookies, and returns the snippet for its pages. $3.00 a call.
- [analytics_install](https://conecto.chat/tools/analytics/analytics_install.md): Step-by-step instructions to put the counting script on a site: any html, Shopify, WordPress, Webflow or Google Tag Manager. Free up to 1,000,000 reads a month.
- [analytics_stats](https://conecto.chat/tools/analytics/analytics_stats.md): A site's visitors, pages, sources, countries, devices, events, goals and speed for a period, against the period before. Free up to 1,000,000 reads a month.
- [analytics_breakdown](https://conecto.chat/tools/analytics/analytics_breakdown.md): One event or goal by a prop or by where its visits came from, with conversions, conversion rate and revenue. Free up to 1,000,000 reads a month.
- [analytics_realtime](https://conecto.chat/tools/analytics/analytics_realtime.md): Visitors in the last 5 minutes, and the pages people looked at in the last 30. Free up to 1,000,000 reads a month.
- [analytics_set_goals](https://conecto.chat/tools/analytics/analytics_set_goals.md): Sets the conversions a site counts: pages reached or events, replacing its goals; with notify, the agent hears of each one as it happens. Free.
- [analytics_define_events](https://conecto.chat/tools/analytics/analytics_define_events.md): Defines events from what the script already sees (clicks, pages, scrolling, time on a page, props), with nobody editing the site. Free.
- [analytics_funnel](https://conecto.chat/tools/analytics/analytics_funnel.md): How many visitors did each step of a path in order, and how many dropped out at each one. Free up to 1,000,000 reads a month.
- [analytics_paths](https://conecto.chat/tools/analytics/analytics_paths.md): Where visits went after a page and where they came from, or the commonest journeys through the site. Free up to 1,000,000 reads a month.
- [analytics_heatmap](https://conecto.chat/tools/analytics/analytics_heatmap.md): A page's heatmap: the most clicked elements, rage and dead clicks, scroll depth and time on page, with a link that draws it. Free up to 1,000,000 reads a month.
- [analytics_problems](https://conecto.chat/tools/analytics/analytics_problems.md): Pages that answered an error to visitors, JavaScript errors, and where people rage-click or click with nothing happening. Free up to 1,000,000 reads a month.
- [analytics_web_vitals](https://conecto.chat/tools/analytics/analytics_web_vitals.md): How fast the site's pages are for real visitors: Core Web Vitals at the 75th percentile, rated the way Google rates them. Free up to 1,000,000 reads a month.
- [analytics_view_link](https://conecto.chat/tools/analytics/analytics_view_link.md): A one-time link to a page that shows a site's stats to a person. Free.
- [analytics_update_site](https://conecto.chat/tools/analytics/analytics_update_site.md): Changes a site's name, time zone, traffic alert, weekly summary, JavaScript errors and whether where leads came from is kept with them. Free.
- [analytics_list_sites](https://conecto.chat/tools/analytics/analytics_list_sites.md): Every site this account counts, with this month's events and its snippet. Free up to 1,000,000 reads a month.
- [analytics_add_events](https://conecto.chat/tools/analytics/analytics_add_events.md): Raises a site's monthly event allowance by blocks of a million events. $5.00 per block of a million events a month.
- [analytics_remove_site](https://conecto.chat/tools/analytics/analytics_remove_site.md): Stops counting a site, ends its rent and deletes its stats for good. Free.