The Reporting API allows you to review the data tracked by the Inbenta APIs and SDKs, and the aggregations performed by the Inbenta reporting platform. There are three endpoint categories that correspond to the different types of data Inbenta stores.

Raw events

Raw events are any individual event tracked in an instance. Available events you can retrieve are:

• user questions,
• clicks,
• ratings, and
• session events.

Inbenta will add more events as tracking ingestion becomes more flexible.

Because there are so many events tracked every day, Inbenta archives this type of data after 100 days. This means that data older than 100 days is not accessible through the Reporting API's raw events endpoint.

Raw events give you the maximum level of detail about the actions performed by your users; however, to see the whole picture of how users actually interact with your product, Inbenta aggregates raw data. This is the next type of event that you can view with the Reporting API.

Aggregates

Aggregates are raw events that are grouped together based on a given configuration. This provides better material for analysis purposes, where related events are linked and you can draw conclusions for the resulting patterns that emerge.

For example, in a given session, raw events would be all the events that happened during this session (a search, a content that matched, a click on that content, etc.). An aggregate could be a summary that counts how many occurrences of each type of event happened over a given period of time, or the total number of user questions over a given period of time,  grouping these raw events based on the user input.

The Reporting API provides two endpoints for aggregates. The first endpoint shows the aggregates metadata. It tells you what aggregates are available for your instance, how they are structured, what fields they have, and what filters are allowed. They are structured like this:

• Key: The name of the aggregate. This is a unique identifier.
• Description: A quick description of the purpose of the aggregate.
• Dimensions: Dimensions are data attributes. They represent the different perspectives through which you can analyze your data (e.g. date, period of time, environment, user type, user question, content id, etc.).
• Metrics: Metrics are quantitative measurements based on dimensions (e.g. total user questions, average clicks, session duration, etc.).
• Filter by: You can use some properties as filters to sort through aggregates. Note that not all properties (dimensions and metrics) are available as filters, because some properties are not designed to be used in searches.

The second endpoint allows you to use filters to request a particular aggregate.

Types

Internally, metrics and dimensions can have different types (e.g. "string", "bool" for booleans, "int" for integers, array, etc.). Metrics are typically numerical, with the "int" type. Dimensions can be any type. "Int" fields allow you to use an X-Y range as a filter, where X and Y are two numbers (e.g. if you want to filter sessions that have a duration of between 10 and 20 seconds, you can use the filter "duration=10-20").

Timezones

Your instance is configured to a set of timezones. You can use timezones as a filter, but this depends on the instance that you request: If you request a timezone that is not enabled for that instance, the Reporting API does not return any value for the aggregates.

You can view and edit the timezones of your instance in your App under Administration > Instances:

Aggributes

Aggributes are entities that exist between raw events and aggregates. When an aggregate is created, some properties of the relevant raw events become dimensions of this aggregate. When it happens, the format of these properties may change. For example, session events send the data key in plain text (e.g. "SEARCH"), but the corresponding aggregate for session details retrieves a set of numerical data key identifiers (e.g. "1"). There are two reasons for this: First, numerical values are easier to store. Second, this makes sure that if the name of a data key changes, it does not affect the aggregate.

Aggributes serve as a connection between the plain text value and the data key identifier. An aggribute for data keys matches the numerical IDs to their strings (e.g. a for SEARCH, 2 for CLICK, etc.). Sources are another example: Sources are ingested dynamically by taking the free text strings sent with raw events, but aggregates return a "id_source" with a unique identifier. You can use aggributes to match the two properties together.

Example

The Reporting API may be used to build a Dashboard with specific metrics from different sources. Click here to see an example that uses the Reporting API to build a multi-instance reporting application.