Event Tracking Overview

Events are the foundation of SegOps. Learn how to send events, identify users, and understand the ingestion pipeline.

SDK vs REST API#

You have two ways to send events:

SDK — official libraries for TypeScript/JS, Go, Swift, and Kotlin. They handle batching, retries, and graceful shutdown automatically.
REST API — direct HTTP calls to /api/ingestion/track/. Best for languages without an official SDK or when you need fine-grained control.

For server-side use, the SDK is strongly recommended. It batches events for efficiency and retries transient failures automatically.

The Event Schema#

Field	Type	Required	Description
user_id	string	Yes	Your unique user identifier (email, UUID, etc.)
event_type	string	Yes	Snake-case event name, e.g. page_viewed
occurred_at	string	No	ISO 8601 timestamp. Defaults to server receive time
payload	object	No	Arbitrary key→value properties

ℹ Note

Event types should be snake_case and descriptive: order_placed, trial_started, page_viewed, search_performed. Avoid spaces, camelCase, or overly generic names like action.

Single vs Batch#

The REST API offers two endpoints. For most use cases, prefer batch:

POST /api/ingestion/track/ — single event
POST /api/ingestion/track/batch/ — up to 500 events per request

Code Examples#

TypeScript SDK

typescript

import { SegOpsClient } from '@segops/sdk';

const segops = new SegOpsClient({
  apiUrl: 'https://api.segops.ai',
  apiKey: process.env.SEGOPS_API_KEY!,
});

// Track a single event (queued, sent in batches)
segops.track({
  userId: 'user-123',
  eventType: 'order_placed',
  payload: {
    order_id: 'ord-456',
    total: 89.95,
    currency: 'USD',
  },
});

REST API (curl)

bash

curl -X POST https://api.segops.ai/api/ingestion/track/batch/ \
  -H "Authorization: ApiKey sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "user_id": "user-123",
        "event_type": "order_placed",
        "payload": { "total": 89.95, "currency": "USD" }
      },
      {
        "user_id": "user-456",
        "event_type": "page_viewed",
        "payload": { "path": "/pricing" }
      }
    ]
  }'

User Identification#

Send a context_identifiedevent to set or update a user's traits. These traits become available as user_property conditions in segment rules.

typescript

segops.identify({
  userId: 'user-123',
  traits: {
    email: '[email protected]',
    plan: 'starter',
    company: 'Acme Corp',
    country: 'US',
  },
});

Rate Limits by Plan#

Plan	Events / month	API calls / min
Free	500,000	60
Starter	5,000,000	300
Business	50,000,000	1,000
Enterprise	Unlimited	Custom

When the monthly event limit is reached, the API returns 429 Too Many Requestswith a Retry-After header indicating when the limit resets.

The Ingestion Pipeline#

Events flow through a multi-stage pipeline designed for high throughput and low latency:

Your app sends events to the REST API (/api/ingestion/track/)
The API validates and publishes events to our realtime event stream (Google Cloud Pub/Sub)
A Go ingestor worker subscribes to the stream and writes to the analytics warehouse (ClickHouse)
Events are available for query within ~2 seconds of receipt

The response to your track call is 202 Accepted — the event is queued, not immediately visible in the analytics warehouse. For most use cases this delay is invisible; if you need immediate consistency (e.g., during testing), wait ~3 seconds before querying.

Monitoring Ingestion#

Open the Ingestion section in the app sidebar to see:

Event volume timeseries (24h / 7d)
Top event types by count
Unique user count
Recent ingestion errors (schema violations, malformed payloads)
Pipeline health status (event stream, ingestor worker, analytics warehouse)

← PreviousCondition Reference Next →Event Schemas