Has someone just told you that they need you to run an Analytics export using the Analytics Reports API and pointed you to the API documentation? Did you stare at that documentation thinking, “What am I supposed to do with this? What’s an API?”

Don’t worry. We’ve got you. This tutorial walks you through the steps to use the Analytics API documentation and get you started with some simple tools that will allow you to generate the export and access the export data. When you’re done, you’re going to feel like a rock star.

👍

Tip

If you're a seasoned developer who is comfortable with REST APIs and cURL examples, see Analytics Reports API quickstart.

We’re going to generate a Raw Conversation export. First, we’ll generate the default export with all columns listed. Then, we’ll show you how to run a export filtering the data down to just the columns you want. You’ll be able to take the skills you learn here and apply them to run any future Care Analytics exports.

How to use this guide

If you’re new to working with APIs, you’ll need to learn a few things before we can get started with the tutorial. While it might feel like it’s taking a while to get to the good stuff, the overview and information sections are important.

• Before you begin helps you choose and install the tool to run your exports
• Have this information handy lists information you’ll need to use the Analytics Reports API
• Basic Steps is an abridged version of the steps in the tutorial. Use it as a shortcut when you run reports in the future.
• Choose which export to run, Determine which columns to include in the report, and Understand the API request contain useful reference material that will help you understand how to use the API and understand the API documentation

This section is where the tutorial actually begins:

• Run and download the export using Postman

Before you begin

Download Postman

Postman is a user-friendly app that enables you to make requests to REST APIs like the Analytics Reports API. We aren’t going to get into what a REST API is in this tutorial. Just understand that we’re going to make a request to the Analytics Reports API and Postman is going to help us do that. Get Postman here.

• During setup, you’ll need to create an account and supply an email address.
• Select the Debugging and Manual testing workspace option
• Skip the Postman Team Setup

Have this information handy

Contact your Khoros Care administrator and get the following information:

• The username and password for the dedicated Analytics Reports API user account(s) used for your Khoros Care instance.
• Your Analytics API URL. Generally:
  • If your data is hosted in the US, the API URL is analytics-api.app.lithium.com
  • If your data is hosted in EMEA, the API URL is analytics-api-emea.app.lithium.com
• Your Analytics API Company Key.

Basic Steps

These are the basic steps to running an Analytics export with the API. Don’t worry if you don’t understand all of the terms in this section yet. We’ll do a detailed walkthrough in the next sections. Use this section as a shortcut after you’ve run a few exports and understand the process.

1. Identify the export you want to run.
2. Determine if you want the export to include all columns or only a subset of columns. (See Define columns to return in an export for additional information.)
3. In Postman make a POST request to one of these endpoints:

• /api/public/reports/report/{report_type}
• /api/public/reports/report/marketing/{report_type}

4. Look for the statusUrl in the response to your POST request.
5. Make a GET request to the URL given in statusUrl. If the runnerState is CLOSED and detail is COMPLETED, then the export is ready for download.

📘

Note

If the job is Complete and ready to be downloaded, calling the status URL will give you the download URL. If you do not see the downloadUrl populated, wait a bit and try the request to the statusUrl again.

6. Run the downloadUrl if the export is finished
7. Save the file to your computer.

Choose which export to run

We list the exports supported by the API in the About Care Analytics Reports guide in our developer documentation. For this tutorial, we’re going to generate a Raw Conversation export. The API calls this export conversation.

In a separate tab. open the API reference documentation for the export. (We link to the endpoint for each export in the table below.) The reference documentation is going to tell us different ways we can filter and format the data provided in our export. For this tutorial, open the Raw Conversations export reference.

Determine which columns to include in the export

These articles in the Khoros Care Analytics knowledge base list and describe the columns included in our Analytics Reports:

• Team performance analytics
• Export raw data from Social Response Analytics
• Export raw brand post data from Publishing analytics

If you want to display only a subset of columns in your export:

1. Review the Admin documentation listed above and note those column names.
2. Get the corresponding column name used by the API.
   The API wants column names in a specific format when you run the export. We list the column names used by the API in reportMetrics values by export type. Generally, the names will look similar. For example, Time Zone is displayed in the Analytics UI, while TIME_ZONE is used by the API.

In this tutorial, we’ll generate the Raw Conversation export twice -- once including all columns, and then again including only the Conversation ID, Status, and Assignee ID columns.

• Conversation ID → CONVERSATION_ID
• Status → STATUS
• Assignee ID → ASSIGNED_AGENT_DISPLAY_ID

Determine data filters

Each export supports a set of filters that define what data to return.

Example of filters include:

• During business hours
• Conversation priority
• Smart view ID
• Work queue ID
• Agent ID
• Include turned off agents
• Team IDs
• Campaign ID (for Raw Brand Post exports)

We list and describe the query parameters used with each export in the API reference documentation for each export. (Get the link to the documentation for each export in the table above.) When you read the documentation, note the required query parameters -- they are marked with a red asterisk (*).

Here is an example of the documentation for the Raw Conversation endpoint. We'll talk about how to define these filters in the next section.

Understand the API request

In this section, we’re going to describe some concepts and terms that you’re going to see throughout this guide.

To generate an export using the API, you’re going to make a request. The request tells the API exactly what you want it to do. We make the request to an endpoint. Each export has a specific endpoint. The endpoint looks something like this:

POST /api/public/reports/report/{report_type}

{report_type} will be one of the API export names listed in the table above. For the Raw Conversation export, we’re going to run in this tutorial, we will use the POST /api/public/reports/report/conversation endpoint.

The POST part of the endpoint is the action. You can think of POST as creating something new (like a new export). You will use POST as the action for most exports you generate.

👍

Tip

For beginners, the GET action is best to generate a Conversation Actions or User export. (We’ll talk about this later - for now don’t worry about it.)

When we make the API request, we write it so that it looks like a URL that you’d type into a browser. Our request to run the Raw Conversations export will look like this:

https://[ANALYTICS API URL]/api/public/reports/report/conversation?reportFormat=csv&locale=en_US&companyKey=<put_your_company_key_here>&startTime=1551441600000&endTime=1556712000000

🚧

startTime and endTime

The values for startTime and endTime are in milliseconds (Epoch). Online converters such as http://www.epochconverter.com/ provide a 'human date to timestamp' conversion option.

This request creates a Raw Conversation export format of open conversations from February 1, 2019 to May 1, 2019 in CSV format in US English. (Notice that I’ve got a placeholder for where to put your company key.)

📘

Note

This request will return all columns in the export. We’ll show how to return only specific columns later.

Let’s look at the first half:

https://[ANALYTICS API URL]/api/public/reports/report/{report_type}

When you generate an export:

• You’ll replace [ANALYTICS API URL] with the Analytics API URL you received from your Response administrator. Either analytics-api.app.lithium.com or analytics-api-emea.app.lithium.com.
• You’ll replace {report_type} with the API export name from the table above.

Let’s look at the second half:

?reportFormat=csv&locale=en_US&companyKey={put_your_company_key_here}&startTime=1551441600000&endTime=1556712000000

In the second part of our request, we add query parameters.

Query parameters provide details for how to build the export. All exports require certain query parameters and some export have optional query parameters that you can add to further define how filter and format the data. (This is where you'll use those filters we talked about in the Determine data filters section.)

👍

Tip

Remember to review the API documentation for the list of query parameters supported and required for each export. (Get the link to the documentation for each export in the table above.)

In the request, query parameters go after the {report_type}. We separate the query parameters from the first part of our request with a question mark (?). You list all query parameters and their values one after another, separated by the ampersand character (&) like this:

?reportFormat=csv&locale=en_US&companyKey=put_your_company_key_here&startTime=1551441600000&endTime=1556712000000

Let’s look at what these query parameters mean.

• reportFormat - this instructs the API to return the export in CSV format. By default, the export is returned in JSON format, which is better for developers but not as useful for normal people like us. CSV, as you probably know, can be imported into Excel and other tools to view and analyze export data. If you want your export in CSV format, you must use reportFormat=csv in your query parameter list.
• locale - the language/local to use for your export. This parameter is optional.
• companyKey - this is the key we talked about in Before You Begin. The companyKey parameter is always required.
• startTime - the start time for the data returned in the export. The startTime parameter is always required.
• endTime - the end time for the data returned in the export. The endTime parameter is always required.
  The startTime and endTime values must be in epoch milliseconds format. That’s simply a certain date and time format that is more efficient for the API to process. You get your export start and end times in epoch milliseconds using an epoch milliseconds converter. You can find many of these on the internet. Here’s and example of the one I’m using for this tutorial.
  
  Type in a user-friendly date and the converter will convert it to the epoch milliseconds equivalent.

Go ahead and try it out.

In an epoch milliseconds converter, convert August 14, 2019 1:00:00 AM using an epoch millis converter.

You should get 1565769600000.

Run and download the export using Postman

We have a quick walkthrough video that provides an overview of the steps we’re about to take. (See this post to access the video.) We’ll go through each step of the video below.

If you haven’t already, download Postman.

Run the export

1. Open Postman.
2. If you see a popup window like this, close it.

3. Click the plus icon (+).

4. Select POST from the dropdown menu.

🚧

Important

If you want to run a Conversation Actions or User export, select GET instead of POST.

5. Copy this URL

https://analytics-api.app.lithium.com/api/public/reports/report/conversation?reportFormat=csv&locale=en_US&companyKey=put_your_company_key_here&startTime=1551441600000&endTime=1556712000000

6. Paste it in the Enter request URL text box.

7. Check the Analytics API URL. If your Response instance is hosted in EMEA, change the API URL to analytics-api-emea.app.lithium.com.
8. Add your company key.

9. Select the Authorization tab.

10. Select Basic Auth from the Type dropdown and then enter the username and password of the API Analytics user in the Username and Password fields.

11. Go back to the Params tab.
12. Click Send.
    You should see a response to your request that looks something like this appear at the bottom of the app. If you see "status": "PASS", the request was successful.

Run a export with a subset of columns

Let’s try running that same export but with only a subset of columns.
We’re going to add a new query parameter for each column we want to include in the export.

We use the reportMetrics query parameter to define each column we want.

We’ll use these as the values for each reportMetrics parameter we add:

• CONVERSATION_ID
• STATUS
• ASSIGNED_AGENT_DISPLAY_ID

You can either open a new tab in Postman and make a new POST request with this URL:

https://analytics-api.app.lithium.com/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

🚧

Important

Remember to use the correct API URL, update your company key, and add Basic Auth credentials in the Authorization tab.

Or, you can return to the tab where you made your first POST request and add the new query parameters manually.

Click Send.

Check whether the export has finished

We’ll check the status to see if the export has finished generating.

1. In the response, click the statusUrl link.
2. The URL is added into a new request in a new tab in Postman.
   This time we’re going to use GET as the request action because we want to get the status.

3. Go to the Authorization tab.
4. From the Type dropdown, select Basic Auth.
5. Enter the Username and Password for the API Analytics User.
6. Click Send.
   The response will look something like this. If we see "runnerState": "CLOSED", the export is finished running and is ready to be downloaded. If the runnerState is "RUNNING", then wait for a bit and then run repeat these steps until "runnerState": "CLOSED". When the runnerState is CLOSED and the detail field below it is COMPLETED, the export is ready to download.

Download the export

1. Go back to the response, click the downloadUrl link.

🚧

Important

If you do not see a URL in the downloadUrl field, then the export is not ready. Wait a bit, make the request to the statusUrl again. When the export is ready, the downloadUrl fields will be populated.

❗️

Critical

The download URL is only valid for 24 hours. After that time, the report will need to be re-exported to be accessible.

The URL is added into a new request in a new tab in Postman.
We’re going to use GET as the request action again because we want to get the export.

3. Go to the Authorization tab.
4. From the Type dropdown, select Basic Auth.
5. Enter the Username and Password for the API Analytics User.
6. Click Send.
   The response will look something like this.

You've just generated and downloaded a Analytics Report export using the API. Nice job!