Track Event

Send custom events to track user actions and behaviors

POST /track

Track Event

cURL

curl --request POST \
  --url https://api.example.com/track \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "<string>",
  "namespace": "<string>",
  "timestamp": {},
  "properties": {},
  "anonymousId": "<string>",
  "sessionId": "<string>",
  "websiteId": "<string>",
  "source": "<string>"
}
'

200

{
  "status": "<string>",
  "type": "<string>",
  "count": 123,
  "message": "<string>"
}

The track endpoint allows you to send custom events with optional properties to track specific user actions and behaviors in your application.

Authentication

This endpoint supports two authentication methods:

1. API Key: Include your API key in the Authorization header. The API key must have the track:events scope.
2. Website ID: Pass website_id as a query parameter for client-side tracking.

Request

Headers

Authorization · string

Bearer token with your API key (required if not using website_id)

Content-Type · string · required

Must be application/json

Query Parameters

website_id · string

UUID of the website. Required if not using API key authentication.

Body Parameters

You can send either a single event object or an array of event objects.

name · string · required

Name of the event (1-256 characters)

namespace · string

Namespace to organize events (max 64 characters)

timestamp · number | string | date

Event timestamp. Accepts Unix timestamp (ms), ISO date string, or Date object. Defaults to current time.

properties · object

Custom properties as key-value pairs. Can contain any JSON-serializable data.

anonymousId · string

Anonymous user identifier (max 256 characters)

sessionId · string

Session identifier (max 256 characters)

websiteId · uuid

UUID of the website. Can be specified per event in batch requests.

source · string

Source of the event (max 64 characters)

Response

status · string

Status of the request: success or error

type · string

Type of event processed: custom_event

count · number

Number of events successfully processed

message · string

Error message (only present when status is error)

Examples

Single Event

curl -X POST https://api.databuddy.io/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "button_clicked",
    "namespace": "ui",
    "properties": {
      "button_id": "signup",
      "page": "/pricing"
    },
    "anonymousId": "user-123",
    "sessionId": "session-456"
  }'

Response

{
  "status": "success",
  "type": "custom_event",
  "count": 1
}

Multiple Events

curl -X POST https://api.databuddy.io/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "page_viewed",
      "properties": {
        "path": "/dashboard"
      }
    },
    {
      "name": "feature_used",
      "namespace": "product",
      "properties": {
        "feature": "export",
        "format": "csv"
      }
    }
  ]'

Response

{
  "status": "success",
  "type": "custom_event",
  "count": 2
}

With Website ID (Client-Side)

curl -X POST https://api.databuddy.io/track?website_id=550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "video_played",
    "properties": {
      "video_id": "intro-2024",
      "duration": 120
    }
  }'

Error Responses

Invalid Request Body

{
  "status": "error",
  "message": "Invalid request body"
}

Missing API Key or Website ID

{
  "status": "error",
  "message": "API key or website_id required"
}

Missing Scope

{
  "status": "error",
  "message": "API key missing track:events scope"
}

Website Not Found

{
  "status": "error",
  "message": "Website not found"
}