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.

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
• Alias Users: Learn when to merge identifiers