Analytics Reports API Quick Start

This quick start will get you up and running with generating and downloading your first export. This guide assumes that you are familiar with REST APIs and cURL. If you are totally new to APIs, try our Beginner's Guide to the Analytics Reports API.

👍
Tip
We recommend reading About Care Analytics Reports before you begin. You will need your company key and an account that has Analytics Reports API granted. Contact your Care administrator if you do not have these keys and permissions.

Identify the export you want to run and find the export ID to use in your request.
Determine the format in which you want the export data: JSON or CSV
Determine if you want the export to include all columns or only a subset of columns.
Determine data filters. (See the API reference for each export endpoint to view supported filters, such as conversation priority, smart view ID, work queue ID, agent ID, team IDs, and campaign ID.
Make a GET request to one of these endpoints. See the API reference for query and path parameters:

/api/public/reports/report/report/<exportId> - for Care exports

/api/public/reports/report/marketing/<exportId> - for Publishing exports

curl -u '[USERNAME]:[PASSWORD]' -XGET 'https://analytics-api.app.lithium.com/api/public/reports/report/conversation?reportFormat=csv&locale=en_US&companyKey=[COMPANY_KEY]&startTime=1551441600000&endTime=1556712000000

curl -u '[USERNAME]:[PASSWORD]' -XGET 'https://analytics-api.app.lithium.com/api/public/reports/report/conversation?locale=en_US&companyKey=[COMPANY_KEY]&startTime=1551441600000&endTime=1556712000000&reportMetrics=CONVERSATION_ID&reportMetrics=STATUS&reportMetrics=ASSIGNED_AGENT_DISPLAY_ID'

🚧
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.

Look for the statusUrl in the response.

{
  "status":"PASS",
  "request":null,
  "message":null,
  "result":{
    "workflowId":"cc645bd3-9def-3d5c-bf05-20efeb11f453",
    "runId":"23IS1+Anp9mm9Bl+C2VZV3UY2T6g4H6eoODJUFQPVpvlI=",
    "downloadUrl":"",
    "statusUrl":"https://analytics-api.app.lithium.com/api/public/reports/report/cc645bd3-9def-3d5c-bf05-20efeb11f453/23IS1%2BAnp9mm9Bl%2BC2VZV3UY2T6g4H6eoODJUFQPVpvlI%3D/status?companyKey=[COMPANY_KEY]"
  }
}

Make a GET request to the URL given in statusUrl.

Look for result.runnerState, result.detail, and downloadUrl in the response.
If result.runnerState is CLOSED and result.detail is COMPLETED, then the export is ready to download and downloadUrl will be populated with an endpoint.
If downloadUrl is not populated, then the export is not finished or the job has failed. Wait a bit longer and try the request to the statusUrl endpoint again.

{
  "status": "PASS",
  "request": null,
  "message": null,
  "result": {
    "jobInfo": {
      "workflowId": "f71ccb0c-afdc-32c6-8bfd-443f8eabae87",
      "runId": "23nUak09Gc3t5K65L3GMQ3Y1onNYtvSsfUSuqEO0+pkHA=",
      "downloadUrl": "https://analytics-api.app.lithium.com/api/public/reports/report/f71ccb0c-afdc-32c6-8bfd-443f8eabae87/23nUak09Gc3t5K65L3GMQ3Y1onNYtvSsfUSuqEO0%2BpkHA%3D/download?analyticsAccessToken=oMqgB5T7BikRH3ISPxlqIw%3D%3D",
      "statusUrl": "https://analytics-api.app.lithium.com/api/public/reports/report/f71ccb0c-afdc-32c6-8bfd-443f8eabae87/23nUak09Gc3t5K65L3GMQ3Y1onNYtvSsfUSuqEO0%2BpkHA%3D/status?analyticsAccessToken=oMqgB5T7BikRH3ISPxlqIw%3D%3D"
    },
    "result": {
      "runnerState": "CLOSED",
      "reason": null,
      "detail": "COMPLETED",
      "currentCount": null,
      "totalCount": null,
      "lastAcknowledgeTime": null
    }
  }
}

{
  "status": "PASS",
  "request": null,
  "message": null,
  "result": [
    {
      "jobInfo": {
        "workflowId": "57113d95-0745-320b-9269-00de3a9a3128",
        "runId": "23g+OxKtvHZugyyn1PN+0y5u7EFFtnRDBbyRjEeXWSRcQ=",
        "downloadUrl": "",
        "statusUrl": "https://analytics-api.app.lithium.com/api/public/reports/report/57113d95-0745-320b-9269-00de3a9a3128/23g%2BOxKtvHZugyyn1PN%2B0y5u7EFFtnRDBbyRjEeXWSRcQ%3D/status?analyticsAccessToken=53u6j8zjSLAe6e%2F8s80LtA%3D%3D"
      },
      "result": {
        "runnerState": "RUNNING",
        "reason": null,
        "detail": "",
        "currentCount": null,
        "totalCount": null,
        "lastAcknowledgeTime": null
      }
    }
  ]
}

{
  "status": "PASS",
  "request": null,
  "message": null,
  "result": [
    {
      "jobInfo": {
        "workflowId": "57113d95-0745-320b-9269-00de3a9a3128",
        "runId": "23g+OxKtvHZugyyn1PN+0y5u7EFFtnRDBbyRjEeXWSRcQ=",
        "downloadUrl": "",
        "statusUrl": "https://analytics-api.app.lithium.com/api/public/reports/report/57113d95-0745-320b-9269-00de3a9a3128/23g%2BOxKtvHZugyyn1PN%2B0y5u7EFFtnRDBbyRjEeXWSRcQ%3D/status?analyticsAccessToken=53u6j8zjSLAe6e%2F8s80LtA%3D%3D"
      },
      "result": {
        "runnerState": "CLOSED",
        "reason": null,
        "detail": "FAILED",
        "currentCount": null,
        "totalCount": null,
        "lastAcknowledgeTime": null
      }
    }
  ]
}

Make a GET request to the endpoint in the downloadUrl field, specifying the full path and filename where you want to export to be downloaded locally.

curl -L -u [USERNAME]:[PASSWORD] \
  'https://analytics-api.app.lithium.com/api/public/reports/report/[workflowId]/[runId]/download?companyKey=[COMPANY_KEY]' 
  -o convoExport19March2020.csv

curl -L -u '[USERNAME]:[PASSWORD] \
  'https://analytics-api.app.lithium.com/api/public/reports/report/88cfc7fe-dfde-3b7d-b201-ec48e640f349/23ojMp0U9YVNcR1JMV0FMLctcCMGPxBlDqA%2FexQnahUI8%3D/status?companyKey=[COMPANY_KEY]'