Product Analytics > Reference > Product Analytics API – Docs

Product Analytics API

The Altertable Product Analytics API provides direct HTTP access to track events and identify users. For most use cases, we recommend using the JavaScript or React SDKs, which provide a simpler interface and handle session management automatically.

Base URL

All API requests should be made to:

https://api.altertable.ai

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See the Authentication guide for details on obtaining and managing API keys.

Track Events

Endpoint

POST /track

Request Format

{
  "event": "Button Clicked",
  "properties": {
    "button_name": "Sign Up",
    "location": "header"
  },
  "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
  "device_id": "device-0197d9df-3c3b-734e-96dd-dfda52b0167c",
  "timestamp": "2025-01-15T10:30:00Z"
}

Request Parameters

Parameter	Type	Required	Description
`event`	`string`	Yes	The event name
`properties`	`object`	No	Custom event properties (key-value pairs)
`distinct_id`	`string`	Yes	The distinct ID (user ID or visitor ID)
`device_id`	`string`	No	The device ID (persists across sessions)
`timestamp`	`string` (ISO 8601)	No	Event timestamp (defaults to current time)

Example Request

curl -X POST https://api.altertable.ai/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Purchase Completed",
    "properties": {
      "product_id": "p_01jza8fr5efvgbxxdd1bwkd0m5",
      "amount": 99.99,
      "currency": "USD"
    },
    "distinct_id": "u_01jza857w4f23s1hf2s61befmw"
  }'

Response

Success (200 OK):

{
  "success": true
}

Error (4xx/5xx):

{
  "error": {
    "message": "Invalid API key",
    "code": "AUTHENTICATION_ERROR"
  }
}

Identify Users

Endpoint

POST /identify

Request Format

{
  "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
  "anonymous_id": "visitor-0197d9df-3c3b-734e-96dd-dfda52b0167c",
  "device_id": "device-0197d9df-3c3b-734e-96dd-dfda52b0167c",
  "traits": {
    "email": "[email protected]",
    "name": "John Doe",
    "plan": "premium",
    "signup_date": "2025-01-01"
  }
}

Request Parameters

Parameter	Type	Required	Description
`distinct_id`	`string`	Yes	The user's unique identifier
`anonymous_id`	`string`	No	The previous visitor ID (for linking anonymous events)
`device_id`	`string`	No	The device ID (persists across sessions)
`traits`	`object`	No	User properties (key-value pairs)

Example Request

curl -X POST https://api.altertable.ai/identify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
    "traits": {
      "email": "[email protected]",
      "name": "John Doe",
      "company": "Acme Corp",
      "plan": "premium"
    }
  }'

Response

Success (200 OK):

{
  "success": true
}

Error (4xx/5xx):

{
  "error": {
    "message": "Invalid distinct_id format",
    "code": "VALIDATION_ERROR"
  }
}

Alias Users

Endpoint

POST /alias

Request Format

{
  "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
  "new_user_id": "new_user_id-019aca6a-1e42-71af-81a0-1e14bbe2ccbd",
  "device_id": "device-0197d9df-3c3b-734e-96dd-dfda52b0167c"
}

Request Parameters

Parameter	Type	Required	Description
`distinct_id`	`string`	Yes	The current user identifier
`new_user_id`	`string`	Yes	The new ID to link to the current identity
`device_id`	`string`	No	The device ID

Example Request

curl -X POST https://api.altertable.ai/alias \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
    "new_user_id": "new_user_id-019aca6a-1e42-71af-81a0-1e14bbe2ccbd"
  }'

Response

Success (200 OK):

{
  "success": true
}

Error (4xx/5xx):

{
  "error": {
    "message": "Invalid new_user_id format",
    "code": "VALIDATION_ERROR"
  }
}

Error Handling

Error Codes

Code	Status	Description
`AUTHENTICATION_ERROR`	401	Invalid or missing API key
`VALIDATION_ERROR`	400	Invalid request format or parameters
`RATE_LIMIT_ERROR`	429	Too many requests
`SERVER_ERROR`	500	Internal server error

Rate Limiting

API requests are rate-limited to prevent abuse. If you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "message": "Rate limit exceeded",
    "code": "RATE_LIMIT_ERROR",
    "retry_after": 60
  }
}

The retry_after field indicates the number of seconds to wait before retrying.

Retry Logic

For production applications, implement exponential backoff retry logic:

Retry on 429 (rate limit) and 5xx (server errors)
Use exponential backoff: wait 1s, then 2s, then 4s, etc.
Respect the retry_after header when provided
Limit retries to avoid infinite loops

Best Practices

Use SDKs when possible: The SDKs handle retries, queuing, and session management automatically
Identify users for better tracking: Use the /identify endpoint to set user context, then include distinct_id in subsequent track requests to associate events with users
Batch events: When sending multiple events, consider using the SDK's built-in batching
Use consistent event names: Use clear, consistent naming conventions for events
Validate data: Ensure event properties and user traits are valid JSON
Monitor errors: Track API errors and implement appropriate retry logic

Next Steps

Use SDKs: Simplify integration with JavaScript or React SDKs
Track Events: Learn more about event tracking
Identify Users: Learn more about user identification