Skip to main content
POST
/
track
Track Event
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>"
}
'
{
  "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"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us