events.track

Track events in PlatformX projects.

Facts


Method	`POST https://api.getdx.com/events.track`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	PlatformX project token passed as an HTTP header.
`name`	`Text`	Name of the event. Example: `action-executed`
`timestamp`	`Text`	String containing the Unix timestamp for when the event occurred. Example: `"1680723287"`
`email` _ required unless github_username or gitlab_username is provided	`Text`	The email address of the user who initiated the event. Example: `jsmith@getdx.com`
`github_username` _ required unless email or gitlab_username is provided	`Text`	The GitHub username of the user who initiated the event. Note: To attribute events by GitHub username, usernames must first be loaded into DX (instructions) Example: `jsmith`
`gitlab_username` * required unless email or github_username is provided	`Text`	The GitLab username of the user who initiated the event. Note: To attribute events by GitLab username, usernames must first be loaded into DX (instructions) Example: `jsmith`

Optional arguments

Name	Type	Description
`metadata`	`JSON`	Additional data about the event that you wish to capture. Metadata must not exceed 1KB in size. Example: `{"color": "blue"}`
`test_data`	`Boolean`	Set this to true to create an event that will bypass the throttling logic and always send a survey, even before it is published. This event and the related response will appear in the app but not in reports or charts. Example: `true`

Example request

This is a typical request:

curl https://api.getdx.com/events.track -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{"name": "your.event", "email": "your.email@example.com", "timestamp":"1680723287" }'

Example response

The response will always contain an ok property which is true when it is successful:

{ "ok": true }

When there is an error, the ok property will be false and details about the error will be included.

{
  "ok": false,
  "error": "invalid_arguments"
}

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok param in the response.

Error	Description
`invalid_arguments`	Check that you are sending the timestamp in the expected format and all required parameters are included.
`invalid_form_data`	Make sure all required parameters are included.
`too_many_requests`	You attempted to send more than 15,000 events per 24h period, or 30 per minute.
`metadata_too_large`	Metadata payload is larger than limit of 1KB