About Care Response Analytics Reports

Learn about the Analytics Reports API

Using Care Response Analytics , you can generate exports from Khoros Response's set of near-real-time metrics to measure your Response teams.

What can I do with the Analytics Reports API?

• Generate Khoros Response and Khoros Publishing exports
• Check the status of an export run job
• Download an export
• Filter exports by
  • business hours
  • conversation priority
  • smart view ID
  • work queue ID
  • agent ID
  • turned off agents
  • team IDs
  • campaign ID (for Raw Brand Post exports)
• Specify the locale of the export (English (US), Spanish (Spain), French, German, Turkish)
• Define columns to return in an export
• Define the timezone used to format dates
• Define the report format: JSON or CSV
• Retrieve timezone IDs
• Retrieve team IDs

What exports can I create?

The Analytics Reports API enables you to generate the exports listed below. You can export to CSV and JSON, pulling data from all export columns or a subset of your choosing. JSON is the default format.

The Export Name is the export title seen in the user interface (UI) and in the Admin guides. The Export ID is the ID used by the Analytics Reports API. Each item in the Export Name column links to the Admin documentation that describes the export. Each item in the Export ID column links to the API reference for the endpoint to call to generate the export.

Export Name (UI)	Export ID (API)
Agent State	raw_agent_states POST /reports/report/raw_agent_states
Combined Raw	combined POST /reports/report/combined
Conversation Actions	conversation_actions GET /reports/report/conversation_actions POST /reports/report/conversation_actions
Conversation History Action	conversation_history_action POST/reports/report/conversation_history_action
Raw Author	author POST /reports/report/author
Raw Brand Post	raw_brand_posts POST /reports/report/marketing/raw_brand_posts
Raw Conversation	conversation POST /reports/report/conversation
Raw Help Request	raw_expert_help POST /reports/report/raw_expert_help
Raw Incoming Post	incoming_post POST /reports/report/incoming_post
Raw Response	response POST /reports/report/response
Response Approval	response_approval POST /reports/report/response_approval
Team Performance	team_performance POST /reports/report/team_performance
Team Performance Interval	team_performance_interval POST /reports/report/team_performance_interval
User	user GET /reports/report/user POST /reports/report/user

Authentication and API URLs

All endpoints require HTTP Basic Authentication. Create a dedicated Analytics API user account and contact Support as described in HTTP authentication to request API access.

To call the Analytics Reports endpoints, use the Analytics API URL displayed in the Analytics API Settings section of your app to call the endpoints. Pass the Analytics API Company Key with each call. Find the company key in Account Admin > General Settings > Analytics API Settings. If you do not see the key, contact your Khoros Response administrator. You might not have the appropriate permissions.

The Analytics API URL differs depending on where your data is hosted:

• EMEA: analytics-api-emea.app.lithium.com
• US: analytics-api.app.lithium.com

If you are unsure where you are hosted, contact Support and ask which data center is used for your instance.

📘

Note

In the example calls in the Analytics API reference, [USERNAME]:[PASSWORD] refers to the credentials used to log in to Khoros Response. The user name is an email address and is case-sensitive.

How do I generate an export?

See the Analytics Reports API quickstart to get started. API newbies might prefer the Beginner's Guide to the Analytics Reports API.

Datatypes and formatting

All fields in all exports are of the datatype String and have a field length of unbounded. Times will be formatted per the Company setting or the Locale that the user specifies when running the export.

Rate limits

Requests made to the Analytics Reports API are rate limited to 20 requests per minute. If you exceed this rate, you will receive an HTTP 429 (“Too many requests”) response, and the response will contain a message indicating what the rate limit is and how many milliseconds you should wait before making another API call.

Throttled because rate limit is exceeded. This resource allows 20 requests/minute. Try again in X milliseconds" where X will be the number of milliseconds before the API will accept a new request

Export formats

By default, the Analytics Reports API generates exports in JSON format. You may specify the export to be in CSV format using the reportFormat query parameter set to csv.

/reports/report/conversation?companyKey=[company_key]&startTime=[start_time]&endTime=[end_time]&reportFormat=csv

Omitting reportFormat from the request generates the export in JSON.

This example includes the reportFormat query parameter used in a request.

Generating an export in CSV format

curl -u username:password -XPOST \
  'https://analytics-api.app.lithium.com/api/public/reports/report/<exportId>?companyKey=[COMPANY_KEY]&startTime=1481212789920&endTime=1481817589920&reportFormat=csv'

📘

Note

By default, export generated by the API return all columns. The one exception is the User export. When you generate an export in JSON format, you receive extra columns with the values of time-related field values in milliseconds. These millisecond fields are not returned if you generate the User export in CSV format.

Reading the export

When you view an export in CSV format, the columns of the export use the column display ID.

Here is an example of a Raw Conversation export. For simplicity, we ran the export to return a subset of columns.

The JSON version of the export does not display the column display ID. Instead, each column has a unique property name. For example the Conversation ID column maps to the conversationId in the JSON export.

JSON

[
  {
    "conversationId":"249906",
    "status":"Assigned",
    "assignedAgentDisplayId":"63fd256c-f7ef-405b-bdaf-fd78ebb1b7d6"
  },
  {
    "conversationId":"254636",
    "status":"Closed - Resolved",
    "assignedAgentDisplayId":""
  },
  ...
  {
    "conversationId":"854682",
    "status":"Closed - Irrelevant",
    "assignedAgentDisplayId":""
  }
]