​
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