API and Webhooks

Analytics API

/analytics/leaderboard

GET /api/v2/analytics/leaderboard HTTP/1.1
Host: https://yoursite.vanillaforums.com

Retrieve data for a site leaderboard.
Authentication: required

Parameters

Parameter Type Description

board string Type of leaderboard

start string Start of the time range (ISO 8601)

end string End of the time range (ISO 8601)

limit integer Maximum number of rows to return. Default: 10

Leaderboards

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.

Output

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.

[
    {
        "id": 53738,
        "position": 1,
        "positionChange": "Rise",
        "previous": 2,
        "url": "http://yoursite.vanillaforums.com/profile?UserID=1234",
        "title": null,
        "count": 921
    },
    {
        "id": 62929,
        "position": 2,
        "positionChange": "Fall",
        "previous": 1,
        "url": "http://yoursite.vanillaforums.com/profile?UserID=5678",
        "title": null,
        "count": 816
    }
]

/analytics/query

POST /api/v2/analytics/query HTTP/1.1
Host: https://yoursite.vanillaforums.com

Perform a query against collected analytics data.
Authentication: required

The body of the request must be a JSON-encoded object. Each property of the object should be a supported parameter.

Parameters

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

Analysis types

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 propertyparameter.

Event collections

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.

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 0. -1 is for an anonymized user. This was added for GDPR compliance (it only shows for users in Europe).

point

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:

user_point_add
user_point_remove

Commonly used properties for the point collection are:

point.given.points: The total number of points granted or revoked in this event.

post

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:

discussion_add
comment_add

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: This will be true if this event was triggered by a comment and it was the first comment on the discussion.

post_modify

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:

discussion_edit
discussion_delete
comment_add
comment_delete

qna

The qna collection contains events specifically related to the Q&A addon, 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:

answer_accepted

reaction

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:

reaction_add
reaction_delete

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 (e.g., Like, Up, Down, Agree, etc.).
reaction.recordType: The type of post this reaction was performed on. This is typically “discussion” or “comment.”

registration

Successful sign-ups on the forum are recorded in the registration collection.

Valid types for the registration collection are:

registration_success

session

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:

session_start
session_end

Filters

Data queried from analytics can be filtered by collection and event properties. The most common type of filtering is based on the type property. For example, if you want 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: prop and 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:

{
    "filters": [
        {
            "prop": "type",
            "op": "eq",
            "val": "comment_add"
        },
        {
            "prop": "discussionType",
            "op": "eq",
            "val": "Question"
        },
        {
            "prop": "commentMetric.firstComment",
            "op": "eq",
            "val": true
        }
    ]
}

Interval

An optional 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:

hourly
daily
weekly
monthly

Output

Depending on whether or not an interval parameter was specified, the result may be in two different formats.

Without an interval parameter, a single value is returned: result.

{"result": 1370}

If an 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.

{
  "result": [
    {
      "value": 458,
      "timeframe": {
        "start": T00:00:00.000Z",
        "end": T00:00:00.000Z"
      }
    },
    {
      "value": 431,
      "timeframe": {
        "start": T00:00:00.000Z",
        "end": T00:00:00.000Z"
      }
    },
    {
      "value": 481,
      "timeframe": {
        "start": T00:00:00.000Z",
        "end": T00:00:00.000Z"
      }
    }
  ]
}