API reference
Ingestion
Events and traits, from browsers or servers.
Track events#
post/events
One event, or an array of up to 100 with the same publicKey. A batch is all or nothing: an invalid event is named (events[3].occurredAt) and none are stored. Counts 600 events per minute per project. Events for a suppressed (erased) end user are dropped and counted under suppressed.
Parameters
Idempotency-KeystringFor a single event without its own idempotencyKey.
Body
publicKeystringrequiredThe project's public key (
phk_live_…) from its project page. max 200 charsdistinctIdstring | numberrequiredYour stable id for the end user. Numbers are converted to strings; surrounding spaces are trimmed. Don't use an email address or other personal data. Up to 256 characters.
namestringrequiredEvent name, up to 200 characters. Trimmed; blank is refused.
propertiesobjectEvent properties: a JSON object (not an array), up to 32 KB as JSON, 5 levels deep, keys up to 256 characters. No NUL characters or unpaired surrogates anywhere.
occurredAtstringWhen the event happened, ISO 8601 (stored as UTC). Defaults to when Tug receives it. Must be in 2000 or later and at most an hour ahead of Tug's clock. Use it to backfill.
idempotencyKeystringUp to 128 characters. The same key again for the project is stored once and counted under duplicates. Both SDKs set one on every event.
sessionIdstringUp to 128 characters.
urlstringPage URL. Longer than 2048 characters is cut to that length, not refused.
curl -X POST "https://tughq.com/api/v1/events" \
-H "Content-Type: application/json" \
-d '{
"publicKey": "phk_live_3kV9xQmR2pT8wYc1Ld5NbA",
"distinctId": "user_123",
"name": "signup_completed",
"properties": {
"plan": "pro"
},
"occurredAt": "2026-11-22T16:41:00.000Z",
"idempotencyKey": "signup-user_123",
"sessionId": "s_8f2a1c",
"url": "https://app.example.com/signup"
}'200 response · JSON
{
"ok": true,
"accepted": 1,
"duplicates": 0,
"suppressed": 0
}Identify a user#
post/identify
Merge traits onto one end user (new keys added, existing keys replaced). Needs an active plan but doesn't count toward event limits. 300 requests per minute per project.
Body
publicKeystringrequiredThe project's public key (
phk_live_…) from its project page. max 200 charsdistinctIdstring | numberrequiredYour stable id for the end user. Numbers are converted to strings; surrounding spaces are trimmed. Don't use an email address or other personal data. Up to 256 characters.
traitsobjectTraits to merge: a JSON object (not an array), up to 32 KB as JSON, 5 levels deep, keys up to 256 characters. No NUL characters or unpaired surrogates anywhere.
curl -X POST "https://tughq.com/api/v1/identify" \
-H "Content-Type: application/json" \
-d '{
"publicKey": "phk_live_3kV9xQmR2pT8wYc1Ld5NbA",
"distinctId": "user_123",
"traits": {
"plan": "trial"
}
}'200 response · JSON
{
"ok": true
}