The Analytics Reports API endpoints /reports/report/<report_type> and /reports/report/marketing/<report_type> generate Care Analytics exports. By default, the endpoints return the same default columns you would see if ran the export from the Care Analytics user interface (UI).

When to use the reportMetrics query parameter?

Sometimes, you might not want the default set of columns. You can override the default behavior and explicitly define which columns to include in an export with the reportMetrics query parameter.

Deliver a leaner set of information
You can also use reportMetrics to simply retrieve a subset of columns when needed. For example, you might want to run a Raw Conversation export, but you only care about the Conversation ID, Status, and Agent ID columns.

Return turned off columns in an export

Khoros often turns off new columns for a short while when we first release them to avoid breaking existing client implementations and scripts until the customer has time to test the new columns. Likewise, if we have released a new column in Early Access, the column will be turned off for all customers except for those participating in the Early Access program. By default, the /reports/report/<report_type> and /reports/report/marketing/<report_type> endpoints respect these same column visibility configurations.

The reportMetrics query parameter enables you to bypass column configurations. If you run an export and it is missing a documented column you want, simply re-run the export specifying the full list of all columns to return. This enables you to pull the new data while updating your scripts, without having to request access to columns that might break your existing implementations.

Find the reportMetric value to pass in the request

Suppose we're going to run a Raw Conversation export and we only want to include the Conversation ID, Status, and Assignee ID columns. How do we define that in the request?

See to reportMetrics values by export type for a list of export columns by export type. Each table in the guide lists the following for each column included in the export:

• reportMetric (the metric to use in API requests)
• Column Name (the display ID shown in Care Analytics and in CSV exports)
• jsonPropertyName (the JSON property in the response that maps to the reportMetric and column)

In the table for the export you want to run, review the columns listed under Column Name and note the corresponding value in the reportMetric column. The reportMetric name will be the value of the reportMetric query parameter (e.g. reportMetrics=CONVERSATION_ID).

• The reportMetric value for Conversation ID is CONVERSATION_ID
• The reportMetric value for Status is STATUS
• The reportMetric value for Assignee ID is ASSIGNED_AGENT_DISPLAY_ID

We can see from the jsonPropertyName column that we will use the following JSON properties to access the export data:

• conversationId
• status
• assignedAgentDisplayId

Example

This example generates a Raw Conversation export that includes only the Conversation ID, Status, and Assignee ID columns.

Note that we use a separate reportMetrics query parameter for each column we want to include in the export, separated by ampersands (&).

curl -u 'username:password' -XPOST 'https://<analytics_api_url_goes_here>/api/public/reports/report/conversation?reportFormat=csv&locale=en_US&companyKey=<put_your_company_key_here>&startTime=1551441600000&endTime=1556712000000&reportMetrics=CONVERSATION_ID&reportMetrics=STATUS&reportMetrics=ASSIGNED_AGENT_DISPLAY_ID