> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seerstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Track user actions and system behavior.

Events are the immutable history of what happens in your application. An event consists of a name, a timestamp, and a JSON payload.

## Event Structure

A valid event object contains the following fields:

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| `name` | string | **Yes** | The name of the event (e.g., `signup.completed`). |
| `user_id` | string | No | The ID of the user who performed the action. |
| `data` | object | No | Arbitrary JSON object with event properties. |
| `timestamp` | string | No | ISO 8601 timestamp. Defaults to `now`. |

## Sending Events

Use the `events.capture` method to record an event.

> [tab] TypeScript
>
> ```typescript theme={null}
> import Seerstack from 'seerstack';
>
> const client = new Seerstack({
>   apiKey: process.env['SEERSTACK_API_KEY'],
> });
>
> await client.events.capture({
>   name: 'invoice.paid',
>   user_id: 'cus_8374',
>   data: {
>     invoice_id: 'inv_993',
>     amount: 2000,
>     currency: 'usd'
>   }
> });
> ```

> [tab] Ruby
>
> ```ruby theme={null}
> require "seerstack"
>
> seerstack = Seerstack::Client.new(
>   api_key: ENV["SEERSTACK_API_KEY"]
> )
>
> seerstack.events.capture(
>   name: "invoice.paid",
>   user_id: "cus_8374",
>   data: {
>     invoice_id: "inv_993",
>     amount: 2000,
>     currency: "usd"
>   }
> )
> ```

> [tab] cURL
>
> ```bash theme={null}
> curl -X POST https://api.seerstack.com/capture \
>   -H "Authorization: Bearer $SEERSTACK_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "invoice.paid",
>     "user_id": "cus_8374",
>     "data": {
>       "invoice_id": "inv_993",
>       "amount": 2000,
>       "currency": "usd"
>     }
>   }'
> ```

## Naming Conventions

We recommend using a `noun.verb` syntax for your event names. This keeps your data organized and easy to search.

> [!NOTE]
>
> Event names starting with `$` are reserved for SeerStack system events like
> `$pageview`, `$click`, and `$rageclick`. Avoid using `$` prefixes for your own
> custom events.

> [card] Good
>
> * `project.created`
> * `user.signup`
> * `payment.failed`

> [card] Bad
>
> * `created project`
> * `User Clicked Signup Button`
> * `fail`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.