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

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/databuddy-analytics/Databuddy/llms.txt

Use this file to discover all available pages before exploring further.

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