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

# Define events without touching the site (`analytics_define_events`)

Defines events from what the script already sees (clicks, pages, scrolling, time on a page, props), with nobody editing the site.

The events to count from what the script already sees, replacing the site's defined events: a click (on an element by its words, or by its path from analytics_heatmap), a page reached, a page scrolled past a share, time spent on a page, or an event the site sends narrowed by its props (a link out to calendly.com is {"event": "Outbound link", "props": {"url": "https://calendly.com/*"}}). Nobody edits the site. Page, scroll, time and event rules count backwards over the stored months too; clicks count from now on. A defined event works wherever an event does: analytics_stats, goals, funnels, filters and analytics_breakdown. An empty list removes them.

Price: Free. A call that fails costs nothing.

## Use it when

The business wants to count something the site doesn't send itself, like clicks on a button or reading a page to the end.

- For conversions with a rate and revenue, use [analytics_set_goals](https://conecto.chat/tools/analytics/analytics_set_goals.md).

## Say this to your agent

> Count every click on "Book a fitting" as a lead, and everyone who reads the bike size guide to the end.

## 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 | Up to 50 items. |  |  |
| `events[].name` | string | yes, in each item of `events` | Up to 60 characters. |  |  |
| `events[].kind` | string | yes, in each item of `events` | click: someone clicked an element; page: a page was reached; scroll: a page was scrolled past percent; time: someone spent seconds on a page; event: an event the site already sends, narrowed by its props. | `"click"`, `"page"`, `"scroll"`, `"time"`, `"event"` |  |
| `events[].text` | string | no | click: the element's words, like "Book a demo". Up to 60 characters. |  |  |
| `events[].contains` | boolean | no | click: the words appear anywhere in the element's label. |  |  |
| `events[].element` | string | no | click: the element's path as analytics_heatmap shows it. Up to 300 characters. |  |  |
| `events[].page` | string | no | The page, like /pricing (* for any part); for click and event, only on these pages. Up to 500 characters. |  |  |
| `events[].percent` | integer | no | scroll: how far down. 10 to 100. |  |  |
| `events[].seconds` | integer | no | time: seconds on the page. 5 to 3,600. |  |  |
| `events[].event` | string | no | event: the event the site sends, like "Outbound link". Up to 60 characters. |  |  |
| `events[].props` | object | no | event: its props, * for any part, like {"url": "https://calendly.com/*"}. |  |  |

## Example

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

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

```json
{
  "site": "halversoncycle.example",
  "events": [
    {
      "name": "Fitting click",
      "kind": "click",
      "text": "Book a fitting"
    },
    {
      "name": "Read the size guide",
      "kind": "scroll",
      "page": "/guides/bike-sizes",
      "percent": 75
    }
  ]
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/analytics_define_events \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site": "halversoncycle.example", "events": [{"name": "Fitting click", "kind": "click", "text": "Book a fitting"}, {"name": "Read the size guide", "kind": "scroll", "page": "/guides/bike-sizes", "percent": 75}]}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "analytics_define_events",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "site": {
      "site_id": "613e0cdc-d095-4300-8dc0-5f303fc55d76",
      "domain": "halversoncycle.example",
      "name": "Halverson Cycle & Repair",
      "time_zone": "America/Los_Angeles",
      "snippet": "<script defer src=\"https://cncto.co/a.js\" data-site=\"613e0cdc-d095-4300-8dc0-5f303fc55d76\"></script>",
      "events_this_month": 13,
      "clicks_this_month": 0,
      "allowance_per_month": 100000,
      "extra_blocks": 0,
      "monthly_usd": "$3.00",
      "goals": [],
      "events": [
        {
          "name": "Fitting click",
          "kind": "click",
          "text": "Book a fitting"
        },
        {
          "name": "Read the size guide",
          "kind": "scroll",
          "page": "/guides/bike-sizes",
          "percent": 75
        }
      ],
      "spike_alert_visitors": null,
      "weekly_summary": false,
      "track_errors": false,
      "keep_sources": true,
      "created_at": "2026-10-14T08:00:00+00:00"
    }
  }
}
```

`result`: The site, with the events it now defines.

## 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 or kind, two share a name, the name is one Conecto counts already, or the rule misses what its kind needs. | Fix the event the message names: a click needs text or element; page, scroll and time a page; scroll a percent and time seconds. |

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_track](https://conecto.chat/tools/analytics/analytics_track.md): 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. 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.