Skip to content
DocumentationAPI references
API references
Product Analytics API

HTTP API

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

Successful responses return the same JSON shape: ok, task_id, and error_code.

API endpoint

Hostname
Port
api.altertable.ai
443 (HTTPS)

Authentication

All API requests require a public Product Analytics API key.

Method
Value
X-API-Key header
X-API-Key: YOUR_API_KEY
Authorization header
Authorization: Bearer YOUR_API_KEY
Query parameter
?apiKey=YOUR_API_KEY

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

POST/track

Track one event or a batch of events.
Authentication
Public Product Analytics API key
Permission
Write events

Parameters

syncboolean· query · Optional
Wait for ingestion to finish before returning when true.
environmentstring· body · Required
Environment slug such as production or staging.
eventstring· body · Required
Event name.
propertiesobject· body · Required
Custom key-value properties. Send an empty object when no properties apply.
distinct_idstring· body · Optional
User or visitor identifier.
anonymous_idstring· body · Optional
Anonymous identifier used before the user is known.
device_idstring· body · Optional
Device identifier.
session_idstring· body · Optional
Session identifier.
timestampinteger | ISO 8601 string· body · Optional
Event time as Unix milliseconds or an ISO 8601 timestamp.

The response fields describe whether the API accepted the event:

  • ok: whether the request was accepted
  • task_id: task identifier you can use to track asynchronous processing
  • error_code: endpoint-specific error code when the request was not successful

Error codes

  • environment-not-found
  • product-analytics-not-enabled
  • invalid-headers
  • unknown-built-in-property
  • event-name-too-long
  • property-name-too-long

Event names and property names can contain up to 400 characters. Requests with longer names are rejected before ingestion.

POST/identify

Create or update one identity or a batch of identities.
Authentication
Public Product Analytics API key
Permission
Write identities

Parameters

syncboolean· query · Optional
Wait for ingestion to finish before returning when true.
environmentstring· body · Required
Environment slug such as production or staging.
distinct_idstring· body · Required
The user's unique identifier.
anonymous_idstring· body · Optional
Previous visitor ID used to link anonymous events.
traitsobject· body · Optional
User traits to shallow-merge into the existing identity.
timestampinteger | ISO 8601 string· body · Optional
Timestamp used for last-write-wins ordering.

The response fields describe whether the API accepted the identity:

  • ok: whether the request was accepted
  • task_id: task identifier you can use to track asynchronous processing
  • error_code: endpoint-specific error code when the request was not successful

Error codes

  • environment-not-found
  • product-analytics-not-enabled
  • trait-name-too-long

Trait names can contain up to 400 characters. Requests with longer trait names are rejected before ingestion.

POST/alias

Merge an existing distinct ID into the user ID that should remain.
Authentication
Public Product Analytics API key
Permission
Write identities

Parameters

syncboolean· query · Optional
Wait for the task to finish before returning.
environmentstring· body · Required
Environment slug such as production or staging.
distinct_idstring· body · Required
Existing ID to merge into the target user.
new_user_idstring· body · Required
Target user ID that should remain.

Use /alias only when changing ID systems or attaching an external identifier to a known user. Most login and signup flows should use /identify.

The API also accepts an array of alias payloads for batch merges.

Error codes

  • environment-not-found
  • product-analytics-not-enabled

Best practices

  • Use SDKs when possible: The SDKs handle retries, queuing, and session management automatically
  • Identify users for better tracking: Use POST /identify to set user context, then include distinct_id in subsequent track requests to associate events with users
  • Batch payloads when needed: Endpoints accept either a single payload or an array
  • Use consistent event names: Use clear, consistent naming conventions for events
  • Validate data: Ensure event properties and user traits are valid JSON
  • Send the environment explicitly: Each endpoint requires an environment field in the request body

Next steps