Retrieve events - Fluid Topics - Latest

Fluid Topics API Reference Guide

Category
Reference Guides
Audience
public
Version
Latest

This web service retrieves user events for analytics purposes.

Use the Events count web service to retrieve the number of events logged for a selected period.

Method Endpoint
POST /analytics/api/v1/events

Request example

The following lines show an example of a JSON request body:

{
  "startDate": "2023-02-14",
  "endDate": "2023-02-20",
  "filters": {
    "name": [
      "khub.search"
    ],
    "user": {
      "group": [
        "ft:administrator",
        "TechWriter"
      ],
      "role": [
        "FEEDBACK_USER"
      ]
    }
  },
  "paging": {
    "page": 1,
    "perPage": 1
  },
  "sortOrder": "latestFirst"
}
Field Type Required? Description
startDate String Yes Expects the inclusive start date of the period. It must be in the past year. Its format can be YYYY-mm-dd, YYYY-mm-ddTHH:MM or YYYY-mm-ddTHH:MM:SS. For more information about date and time formats, see Timestamps.
endDate String No Expects the exclusive end date of the period. The end date is optional and must be later than the start date. Its format can beYYYY-mm-dd, YYYY-mm-ddTHH:MM or YYYY-mm-ddTHH:MM:SS.
filters Object No An optional parameter to filter on only some events.
name Array No An optional list of event names.
user Object No Optional information to filter on only the users whose activity generated the events.
id String No An optional list of user IDs.
group Array No An optional list of user groups.
role Array No An optional list of user roles.
paging Object No An optional element to apply paging to the results.
page Number Yes The page to display. Starts at one. Required if using the paging parameter.
perPage Number Yes The number of results to display per page. Required if using the paging parameter.
sortOrder String No The order of results. Accepted values are LatestFirst and OldestFirst.

Response body

The following lines display an example of the JSON response body:

{
  "startDate": "2023-02-14T00:00:00",
  "endDate": "2023-02-20T00:00:00",
  "paging": {
    "page": 1,
    "perPage": 1,
    "lastPage": false
  },
  "results": [
    {
      "appName": "ft/turnkey-portal",
      "appVersion": "3.11.10",
      "contentLocale": "en-US",
      "datetime": 1645204581760,
      "id": "7a58a750-b3e7-4f23-b477-c646eba26340",
      "name": "khub.search",
      "offline": false,
      "parameters": {
        "searchQuery": {
          "terms": "authentication administration",
          "facets": []
        },
        "searchResponse": {
          "autocorrect": false,
          "nbResults": 1009
        }
      },
      "sessionId": "12345678-abcd-4abc-1234-abcdefghijkl",
      "tenantId": "documentation-docft-stable",
      "uiLocale": "en-US",
      "user": {
        "groups": [
          "ft:administrator",
          "ft:authenticated"
        ],
        "id": "12345678-abcd-4abc-1234-abcdefghijkl",
        "roles": [
          "SAVED_SEARCH_USER",
          "PDF_EXPORT_USER",
          "PERSONAL_BOOK_SHARE_USER",
          "FEEDBACK_USER",
          "ADMIN",
          "RATING_USER",
          "PRINT_USER",
          "PERSONAL_BOOK_USER",
          "PORTAL_ADMIN",
          "COLLECTION_USER",
          "KHUB_ADMIN",
          "HTML_EXPORT_USER"
        ]
      },
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:97.0) Gecko/20100101 Firefox/97.0",
      "userIp": "1.2.3.4"
    }
  ]
}
Field Type Description
startDate String The inclusive start date of the period.
endDate String The exclusive end date of the period. For information about date and time formats, seeDates and Times.
paging Object An optional element that applies paging to the results.
    page Number The current page.
    perPage Number The number of results per page.
    lastPage Boolean Value is true if the current page is the last page.
results Array Information about the events retrieved.
    appName String The name of the application that sent the event.
    appVersion String The version of the application that sent the event.
    contentLocale String The content language configured for the portal at the time of the event.
    datetime String The timestamp of the event.
    id String The event's unique identifier.
    name String The name of the event.
    offline Boolean Value is true if the event was generated in Offline mode.
    parameters Object Data collected by the event.
    sessionId String The session identifier.
    tenantId String The tenant identifier.
    uiLocale String The interface language configured for the portal at the time of the event.
    user Array Information about the user who triggered the event.
        id String The user's unique identifier.
        groups Array The groups to which the user belongs.
        roles Array The user's roles.
    userAgent String The user agent.
    userIp String The user's IP address.
Return code Description
200 OK Returns zero or more results.
400 BAD REQUEST One or more required parameters is missing.
401 UNAUTHORIZED The authorization header was not provided or is invalid.

For a comprehensive list of all possible return codes, see Return codes.