Endpoint Details
URL: https://platform.runonatlas.com/external/event
Method: POST
Authentication: The API requires authentication using an API key.
- Header: x-api-key (Required)
- Value: Provided by Atlas OR one can be created in Settings > API Keys (Required)
Request Parameters
- eventName (string): Name of the event being tracked
- generatedAt (string): ISO 8861 timestamp of event creation
- customerId (string): Unique identifier for the customer
Optional Parameters
- idempotencyKey (string): Globally unique UUID to prevent duplicate event processing. Recommended for ensuring exactly-once event delivery. If not provided, Atlas will generate one based on event payload.
- userId (string): Unique identifier for the end user (the customer’s user)
- data (object): Key-value pair for additional event metadata. Used to provide context for event identification and usage calculation. Can include any relevant information about the event.
Example Request
curl --location --globoff '' \\
--header 'x-api-key: {{API_KEY}}' \\
--data '{
"eventName": "aiFeatureUsed",
"data": {"featureName": "dataExport"},
"generatedAt": "2024-10-25T00:00:00.000Z",
"customerId": "1e74c86e-62ce-4896-b466-e1dbae768e0b",
"userId": "7e63ad67-bae9-4c18-9ec7-33440f39afbf",
"idempotencyKey": "test-key"
}'
Best Practices
- Always include an idempotencyKey
- Use meaningful event names
- Provide comprehensive data for accurate usage tracking