Retrieve SUVA Analytics Data Through APIs

Use the SUVA Analytics APIs to get conversation interactions, response feedback, session feedback, and weekly user trends.

Important Note: A single request can cover a maximum period of 6-month (183 days). Paginated endpoints return no more than 100 records per page unless a lower limit is specified.

The SUVA Analytics APIs provide programmatic access to analytics data for a specified UID (the unique identifier of your SUVA agent) and reporting period. All analytics endpoints use the POST method and require a valid OAuth access token.

Endpoint	Path	Returns
Interaction data	/interaction-data	Conversation details and chat transcripts
Response feedback	/response-feedback	Positive or negative feedback submitted for individual responses
Chat session feedback	/session-feedback	Ratings and comments submitted for complete chat sessions
Weekly user trends	/weekly-user-trends	Users and their conversation IDs grouped by week

Before You Begin

Complete the following setup before calling an analytics endpoint.

1. Create an API Client

   Refer to this doc to know how to create an API client - Create a New API App.

   Note: While creating the API client, select Suva in the Scope field.

2. Generate an Access Token

   Encode the client ID and client secret as a Base64 string in the format client_id:client_secret, and submit a client credentials request to the OAuth token endpoint. Replace {{hostname}} with your SearchUnify instance URL.

   curl --location 'https://{{hostname}}/oauth/token' \
   					--header 'Authorization: Basic <base64_client_id_and_secret>' \
   						--header 'Cache-Control: no-cache' \
   						--header 'Content-Type: application/x-www-form-urlencoded' \
   						--data-urlencode 'grant_type=client_credentials'

   Token validity: An access token is valid for four hours. Generate a new token after it expires.

3. Identify the Base URL

   Use the hostname of your SearchUnify instance URLin the following base URL:

   https://{{hostname}}/suva/api/v2_suva

   Append the endpoint path shown in each section to construct the complete request URL.

Common Request Requirements

Requirement	Value
HTTP method	POST
Authorization	Bearer <access_token>
Content type	application/json
Date format	YYYY-MM-DD
Maximum date range	183 days
Maximum page size	100 records for paginated data endpoints

The start_date and the end_date values are inclusive. For example, if the start_date is 2026-06-01, then the data for June 1 is included. Similarly, if the end_date is 2026-06-30, then the data for June 30 is included. Use offset and limit to retrieve paginated results where supported.

Error Responses

The APIs can return the following response bodies when a request cannot be completed.

Invalid Request Data

{
				"data": {},
				"message": "Please provide valid data to fetch details",
				"status_code": 400
				}

Unsupported HTTP Method

{
				"data": {},
				"message": "Invalid Method Called",
				"status_code": 405
				}

No Matching Data

{
				"data": {},
				"message": "Date range must be at least 7 days",
				"status_code": 400
				}

Invalid Weekly Trend Date Range

The Weekly User and Conversation Trends API requires a date range of at least seven days and no more than 183 days.

{
				"data": {},
				"message": "Date range must not exceed 183 days",
				"status_code": 400
				}

Security and Implementation Notes

• Store client credentials and access tokens in a secure server-side secrets store.

• Replace all placeholders in the examples before sending a request.

• Regenerate the access token every four hours or when an authentication request fails because the token has expired.

• Use pagination to process large result sets and continue requesting pages until page equals total_page.