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.

Auth: public key, or public key + server API key.

Parameters

  • Idempotency-Keystring

    For a single event without its own idempotencyKey.

Body

Event

  • publicKeystringrequired

    The project's public key (phk_live_…) from its project page. max 200 chars

  • distinctIdstring | numberrequired

    Your 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.

  • namestringrequired

    Event name, up to 200 characters. Trimmed; blank is refused.

  • propertiesobject

    Event 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.

  • occurredAtstring

    When 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.

  • idempotencyKeystring

    Up to 128 characters. The same key again for the project is stored once and counted under duplicates. Both SDKs set one on every event.

  • sessionIdstring

    Up to 128 characters.

  • urlstring

    Page URL. Longer than 2048 characters is cut to that length, not refused.

Or an array of up to 100 of Event

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
}

Errors: invalid_json (400), invalid_request (400), missing_public_key (400), invalid_public_key (401), invalid_api_key (401), trial_expired (402), billing_inactive (402), plan_limit_reached (402), origin_not_allowed (403), api_key_project_mismatch (403), payload_too_large (413), rate_limited (429), internal_error (500), service_unavailable (503).

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.

Auth: public key, or public key + server API key.

Body

  • publicKeystringrequired

    The project's public key (phk_live_…) from its project page. max 200 chars

  • distinctIdstring | numberrequired

    Your 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.

  • traitsobject

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

Errors: invalid_json (400), invalid_request (400), missing_public_key (400), invalid_public_key (401), invalid_api_key (401), trial_expired (402), billing_inactive (402), plan_limit_reached (402), origin_not_allowed (403), api_key_project_mismatch (403), payload_too_large (413), rate_limited (429), internal_error (500), service_unavailable (503).

  • PageOverviewGet started
  • PageQuick startGet started
  • PageConceptsGet started
  • PageScript tag (tug.js)Install
  • PageReactInstall
  • PageNode and serverInstall
  • PageIdentity verificationGuides
  • PageCounting and holdoutsGuides
  • PagePostHogGuides
  • PageEnvironmentsGuides
  • PageData requestsGuides
  • PageOperator consoleGuides