GET /api/v2/analytics/leaderboard HTTP/1.1
Retrieve data for a site leaderboard.
Parameter Type Description
string Type of leaderboard
string Start of the time range (ISO 8601).
string End of the time range (ISO 8601).
integer Maximum number of rows to return. Default: 10.
Leaderboards are specified by the
board parameter. The following are valid values for that parameter:
- top-posters: Users with most posts.
- top-discussion-starters: Users with most discussions.
- top-question-answerers: Users with most answers.
- top-best-answerers: Users with most accepted answers.
- top-member-by-total-reputation: Users by total reputation.
- top-positive-users: Users with the most positive reactions.
- top-member-by-accumulated-reputation: Users by accumulated reputation.
- top-viewed-discussions: Discussions with most views.
- top-commented-discussions: Discussions with most comments.
- top-positive-discussions: Discussions with most positive reactions.
- top-negative-discussions: Discussions with most negative reactions.
- top-viewed-qna-discussions: Questions with most views.
The following is output from an example request for a user leaderboard. It assumes a
limit of three. The record property contains user row data, because this was a user leaderboard. If it had been a discussion leaderboard request, the property would contain details about a discussion.
The record property has been pruned for this example.
POST /api/v2/analytics/query HTTP/1.1
Perform a query against collected analytics data.
The body of the request must be a JSON-encoded object. Each property of the object should be a supported parameter.
Parameter Type Description
type string Type of analysis to perform
collection string Collection of events
start string Start of the time range (ISO 8601).
end string End of the time range (ISO 8601).
property string An event property to perform the analysis on
filters array Event property filters
interval string Result interval
group string An event property to group results by.
Analytics queries require an analysis type. This type will dictate how the data is compiled in the response.
- count: Count the total records.
- sum: Add up all values for a property.
- maximum: Get the maximum value for a property.
- count_unique: Count the total number of unique property values.
- median: Calculate the median value for a property.
Most analysis types are performed on a specific event property, so they require the
property parameter to be specified. count does not require a
All events captured by Vanilla are grouped into one of the following categories. The collection is specified by passing the
collection parameter to the analytics query.
Page views are captured in the
page collection. Any time a guest or registered user loads up a page, it is captured and filed into this collection.
Valid types for the page collection are:
Note on properties
Commonly used properties for the page collection are:
- user.userID: The ID of the user, if available. If there is no current user, either because they aren’t signed in or are a guest, this value will be
-1 is for an anonymized user. This was added for GDPR compliance, it only shows for users in Europe.
Events involving actions affecting a user’s points are stored in the
pointcollection. Both giving and removing points are recorded.
Valid types for the point collection are:
Commonly used properties for the point collection are:
- point.given.points: The total number of points granted or revoked in this event.
When a discussion or comment is made, it is tracked in the
post collection. All posts are contained in this collection: comments, discussions, questions, ideas. There are no restrictions on the type of post.
Valid types for the post collection are:
Commonly used properties for the post collection are:
- discussionType: The type of discussion related to this post.
- commentMetric.time: If the event was triggered by a comment, this property will be populated with the time, in seconds, between when the discussion and comment were added.
- commentMetric.firstComment: Will be true if this event was triggered by a comment and it was the first comment on the discussion.
If a post is modified, the action is captured in the
post_modify collection. Similar to “post”, the type does not matter. Two primary types of modification events are captured: edits and deletes.
Valid types for the post_modify collection are:
qna collection contains events specifically related to the Q&A plug-in, such as answering a question. Adding, editing or deleting a question would be recorded in the “post” collection.
Valid types for the qna collection are:
When a user submits a reaction to a post, it is captured in
reaction. This includes adding and removing reactions.
Valid types for the reaction collection are:
Commonly used properties for the reaction collection are:
- reaction.reactionClass: The class of the reaction. This is typically “Positive” or “Negative”.
- reaction.reactionType: The specific type of the reaction. (Ex. Like, Up, Down, Agree, etc)
- reaction.recordType: The type of post this reaction was performed on. This is typically “discussion” or “comment”.
Successful sign-ups on the forum are recorded in the
Valid types for the registration collection are:
Session events are captured in the
session collection. These events typically include when a user initiates sign-in, starting their session, and when they sign-out, ending their session.
Valid types for the session collection are:
Data queried from analytics can be filtered by collection and event properties. The most common type of filtering would be based on the
type property. For example, if you wanted to see new discussions, you’d query the
post collection and set a filter on the
type property being equal to “discussion_add”. The available types for the various collections are documented in their individual sections. In addition to
type, some additional commonly-used filtering properties are included in those sections, if available.
Each element in the
Filters array should be an object with two properties:
val. An optional property,
op, can be specified. There are several comparison operators to choose from:
- eq: Equal
- ne: Not equal
- gt: Greater than
- gte: Greater than or equal to
- lt: Less than
- lte: Less than or equal to
- in: Verify a property’s value is in an array
For example, when querying the post collection, you could apply a set of filters that only queried the first answers to a question with the following:
interval parameter may be specified in an analytics query. If a valid
interval is specified, the results are broken down into the specified increments over the timeframe.
The valid values for interval are:
Depending on whether or not an
interval parameter was specified, the result may be in two different formats.
interval parameter, a single value is returned:
interval value was provided, the
result value will be an array. Each interval will be returned as an object in that array. The interval’s subset of the overall timeframe will be specified as the
timeframe property. A
valueproperty will indicate the query result for the specified subset.