HTTP API

The Altertable Product Analytics API provides direct HTTP access to track events, identify users, and alias identifiers. 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.

Connection details

Authentication

All API requests require a public Product Analytics API key.

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

POST /track

Track one event or a batch of events.

Query Parameters:

• sync (optional): When sync=true, the API waits for the task to complete before returning.

POST https://api.altertable.ai/track?sync=true
Copy

Request:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
curl -X POST https://api.altertable.ai/track \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment":"production",
    "event": "Purchase Completed",
    "properties": {
      "product_id": "p_01jza8fr5efvgbxxdd1bwkd0m5",
      "amount": 99.99,
      "currency": "USD"
    },
    "distinct_id": "u_01jza857w4f23s1hf2s61befmw"
  }'

Request Body:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
{
  "environment": "production",
  "event": "Button Clicked",
  "properties": {
    "button_name": "Sign Up",
    "location": "header"
  },
  "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
  "device_id": "device-0197d9df-3c3b-734e-96dd-dfda52b0167c",
  "session_id": "sess_0197d9df-3c3b-734e-96dd-dfda52b0167c",
  "timestamp": "2025-01-15T10:30:00Z"
}

Request Parameters:

Response:

Returns 200 OK with a JSON body:

Copy
1
2
3
4
5
{
  "ok": true,
  "task_id": "019d68d4-c4cb-7e40-ad50-fd4b68c2045e",
  "error_code": null
}

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

Query Parameters:

• sync (optional): When sync=true, the API waits for the task to complete before returning.

POST https://api.altertable.ai/identify?sync=true
Copy

Request:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
curl -X POST https://api.altertable.ai/identify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment":"production",
    "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
    "traits": {
      "email": "[email protected]",
      "name": "John Doe",
      "company": "Acme Corp",
      "plan": "premium"
    }
  }'

Request Body:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
{
  "environment": "production",
  "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
  "anonymous_id": "visitor-0197d9df-3c3b-734e-96dd-dfda52b0167c",
  "traits": {
    "email": "[email protected]",
    "name": "John Doe",
    "plan": "premium",
    "signup_date": "2025-01-01"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

Request Parameters:

Response:

Returns 200 OK with a JSON body:

Copy
1
2
3
4
5
{
  "ok": true,
  "task_id": "019d68d4-c4cb-7e40-ad50-fd5bd4956505",
  "error_code": null
}

• 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
• trait-name-too-long

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

POST /alias

Merge one distinct ID into another identity.

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

Query Parameters:

• sync (optional): When sync=true, the API waits for the task to complete before returning.

POST https://api.altertable.ai/alias?sync=true
Copy

Request:

Copy
1
2
3
4
5
6
7
8
curl -X POST https://api.altertable.ai/alias \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment":"production",
    "distinct_id":"legacy:user_123",
    "new_user_id":"u_01jza857w4f23s1hf2s61befmw"
  }'

Request Body:

Copy
1
2
3
4
5
{
  "environment": "production",
  "distinct_id": "legacy:user_123",
  "new_user_id": "u_01jza857w4f23s1hf2s61befmw"
}

Request Parameters:

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

Response:

Returns 200 OK with a JSON body:

Copy
1
2
3
4
5
{
  "ok": true,
  "task_id": "019d68d4-c4cb-7e40-ad50-fd5bd4956505",
  "error_code": null
}

Error codes:

• environment-not-found

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

• Use SDKs: Simplify integration with JavaScript or React SDKs
• Track Events: Learn more about event tracking
• Identify Users: Learn more about user identification
• Aliasing Users: Learn when to merge identifiers