Vitally's Analytics API is an HTTPS API that uses an Authorization header to provide authentication. The API requires you to send an Authorization header containing your API token with every request:
Authorization: Basic [Your token]
To get started, first get the API token for your account by going to the the navigate to your Settings (⚙️) by selecting your Account Logo on the top left and under Connectors select Integrations. Then select Vitally Analytics API (or via Quick Jump Mac: ⌘ + j Windows: Alt + j) . Toggle the switch on the top right to enable the integration.
An example curl request using this header would look like:
curl -X POST https://api.vitally.io/analytics/v1/batch \
-H "Authorization: Basic [your token]" \
-H "Content-Type: application/json" \
-d '[ ...your data... ]'
Rate-Limiting
The default rate limiting is set at 20000 requests / min using a token bucket. A batch request counts as a single request against that budget, regardless of how many messages it contains. Headers returned on every request will show the total limit, the budget remaining, and the number of seconds until one unit of budget refills.
Response Headers
RateLimit-Limit: 20000, 20000;window=60RateLimit-Remaining: 19990RateLimit-Reset: 1
Error
Status Codes
400 - Bad Request- The body of the request needs to be reviewed401 - Unauthorized- There is an issue with the authorization used (API Token/Basic Auth Header)429 Too Many Requests- There are too many requests being made within the allotted timeframe (e.g. over the 20000 requests/min)
Restricting Analytics API Message Types
Vitally supports restricting which message types your Analytics API will accept — for example, blocking track or account messages entirely. This is useful as a security enhancement if you want to limit what changes are accepted via the Analytics API, even in the event that your credentials are accidentally exposed.
How it works:
Requests to a single-message endpoint for a blocked type will return a
400 Bad Request.Within a batch request, blocked messages are automatically ignored. If all messages in a batch are of a blocked type, the entire request will return a
400 Bad Request.