Events API: Track, Batch, and Query User Events

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.

string

required

The name of the event, for example "User Signed Up" or "Order Completed".

string

Your system’s user ID for the person who performed the event. Required if anonymousId is not provided.

string

An ID for users who have not yet been identified. Required if userId is not provided.

object

Key-value metadata about the event, such as order details or page information.

string

ISO 8601 timestamp for when the event occurred. Defaults to the current time if omitted.

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"
  }'

{ "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.

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.

string

Filter results to events performed by a specific user.

string

Filter results to a specific event name.

string

ISO 8601 start date. Returns events on or after this date.

string

ISO 8601 end date. Returns events on or before this date.

number

default:"100"

Number of results to return. Maximum is 1,000.

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

Overview

Endpoints

Events API: Track, Batch, and Query User Events

POST /v1/events

POST /v1/events/batch

GET /v1/events

​POST /v1/events

​POST /v1/events/batch

​GET /v1/events

POST /v1/events

POST /v1/events/batch

GET /v1/events