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

# Events API: Track, Batch, and Query User Events

> POST /v1/events to track a single event. POST /v1/events/batch to track multiple. GET /v1/events to query event history with filters.

The events endpoints let you track user actions and query your event data programmatically, giving you full control over data ingestion and retrieval from your own code.

## POST /v1/events

Track a single event. Use this endpoint when you want to send one event per request.

<ParamField body="event" type="string" required>
  The name of the event, for example `"User Signed Up"` or `"Order Completed"`.
</ParamField>

<ParamField body="userId" type="string">
  Your system's user ID for the person who performed the event. Required if `anonymousId` is not provided.
</ParamField>

<ParamField body="anonymousId" type="string">
  An ID for users who have not yet been identified. Required if `userId` is not provided.
</ParamField>

<ParamField body="properties" type="object">
  Key-value metadata about the event, such as order details or page information.
</ParamField>

<ParamField body="timestamp" type="string">
  ISO 8601 timestamp for when the event occurred. Defaults to the current time if omitted.
</ParamField>

```bash theme={null}
curl -X POST https://api.saytics.com/v1/events \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Order Completed",
    "userId": "user_456",
    "properties": {
      "orderId": "ord_789",
      "amount": 49.99,
      "currency": "USD"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }'
```

```json theme={null}
{ "status": "ok", "received": 1 }
```

## POST /v1/events/batch

Track multiple events in a single request. The request body takes an `events` array where each item follows the same structure as a single event. Batches are limited to 1,000 events per request.

```bash theme={null}
curl -X POST https://api.saytics.com/v1/events/batch \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "event": "Page Viewed", "userId": "user_456", "properties": { "page": "/home" } },
      { "event": "Button Clicked", "userId": "user_456", "properties": { "button": "cta" } }
    ]
  }'
```

## GET /v1/events

Query your event history with optional filters. This endpoint is useful for auditing event data or building custom reporting workflows.

<ParamField query="userId" type="string">
  Filter results to events performed by a specific user.
</ParamField>

<ParamField query="event" type="string">
  Filter results to a specific event name.
</ParamField>

<ParamField query="from" type="string">
  ISO 8601 start date. Returns events on or after this date.
</ParamField>

<ParamField query="to" type="string">
  ISO 8601 end date. Returns events on or before this date.
</ParamField>

<ParamField query="limit" type="number" default="100">
  Number of results to return. Maximum is 1,000.
</ParamField>

```bash theme={null}
curl "https://api.saytics.com/v1/events?userId=user_456&event=Order+Completed&limit=10" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
```