> For the complete documentation index, see [llms.txt](https://docs.uxwizz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uxwizz.com/api/events.md).

# Events

Events attach structured data to a session and pageview, such as a purchase or a submitted form. [Tags](/api/tags.md) are unique strings attached to a session; they are useful for segments and conversion goals.

You can inspect events from **Visitors**. Use [Ask AI](/guides/ask-ai.md) or a [read-only database query](/guides/database-querying.md) to analyze event data. An event does not automatically create a goal or a revenue report.

![Visitor event details with a fictional purchase, product, and value](https://2006615411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Ltuu0c63_YY4iXfi5vJ%2Fuploads%2Fgit-blob-445ce81b847b85459c744dc0e52ab404db6a1899%2Fuxwizz-events-v10.webp?alt=media)

### UST.addEvent(eventData)

Place this code after the tracking snippet, and call it when the action actually succeeds. Avoid duplicate calls on rerenders or retries.

```javascript
UST.addEvent({
    category: 'SHOP',
    action: 'PURCHASED',
    label: 'Football Shoes',
    value: 49.99,
    value_secondary: 15.99,
    item_id: 'SHOE123',
    data: { img: 'prod/img/shoe.png' }
});
```

Use fictional data to test the event. Open the matching session in **Visitors**, inspect its events, and check the values. Do not send passwords, payment details, or other sensitive data in event fields.

#### Input parameters

| Parameter         | Type                                       | Purpose                               |
| ----------------- | ------------------------------------------ | ------------------------------------- |
| `category`        | Required string                            | Event group, such as `SHOP`           |
| `action`          | Required string                            | Action, such as `PURCHASED`           |
| `label`           | Optional string                            | Display label                         |
| `value`           | Optional number                            | Primary numeric value                 |
| `value_secondary` | Optional number                            | Secondary numeric value               |
| `item_id`         | Optional string                            | Item reference, such as a product SKU |
| `data`            | Optional string or JSON-serializable value | Additional details                    |

Strings in `category`, `action`, `label`, and `item_id` have a 128-character database limit. Numeric fields use `DECIMAL(15,2)`: two decimal places and up to thirteen digits before the decimal point.

Non-string `data` is serialized with `JSON.stringify()` before sending. The database column is `TEXT`, which has a byte limit; it is not unlimited storage. Keep event payloads small and do not use them for files or large page snapshots.

For conversion segments, you can also add a tag when the same action succeeds:

```javascript
UST.addTag('purchased');
```

A session with that tag counts once in a matching goal even if it contains several purchase events.

#### Autofilled values

| Field          | Meaning                                   |
| -------------- | ----------------------------------------- |
| `id`           | Event ID                                  |
| `clientid`     | Session ID                                |
| `clientpageid` | Pageview ID                               |
| `date`         | Time the event was inserted on the server |

Keep category and action names consistent across your website so reports compare the same actions.