The Analytics Reports API is a powerful tool. As the saying goes, "With great power comes great responsibility." We want you to take full advantage of our API and we want you to build your reporting in the most successful and efficient manner. Here are some tips and best practices to help you with your integration.

Recommendations for running and queuing exports

A single user (either a user in the app or the API user) can:

• have a maximum of 2 exports actively running. These might or might not run in parallel.
• have up to 5 total export jobs queued (running or waiting to run)
  A single company across all users can:
• have a maximum of 4 exports actively running. These might or might not run in parallel.
• have up to 50 export jobs queued (running or waiting to run)

When users send any new export requests and the queue is already full, the system closes these extra jobs with the reason "User is attempting to run too many exports."

When running exports via the API, the best practice is to queue no more than 2 exports at a time. Wait for one of those to finish before making an API call to start another.

❗️

Important!

We strongly recommend against using the /api/public/reports/jobs endpoint to check the status of a export job. This endpoint will be deprecated and removed in April 2020. Instead, use the URL in the statusUrl field in the response from api/public/reports/report/<report_type> to retrieve the status of an individual export request.

{
    "status": "PASS",
    "request": null,
    "message": null,
    "result": {
        "workflowId": "c868de5e-0757-3eb6-8ba3-efc6d6518707",
        "runId": "23E4QoIuGV0U39tDUFZYhU4qe8p17HvzhPJgwA+x5c3ag=",
        "downloadUrl": "https://analytics-api.app.lithium.com/api/public/reports/report/c868de5e-0757-3eb6-8ba3-efc6d6518707/23E4QoIuGV0U39tDUFZYhU4qe8p17HvzhPJgwA%2Bx5c3ag%3D/download?analyticsAccessToken=X82dojqexTsYkN9OuIBhxw%3D%3D",
        "statusUrl": "https://analytics-api.app.lithium.com/api/public/reports/report/c868de5e-0757-3eb6-8ba3-efc6d6518707/23E4QoIuGV0U39tDUFZYhU4qe8p17HvzhPJgwA%2Bx5c3ag%3D/status?analyticsAccessToken=X82dojqexTsYkN9OuIBhxw%3D%3D"
    }
}

Poll this statusUrl until the status indicates that the export is finished. A runnerState value of CLOSED indicates that the job is finished.

{
  "status": "PASS",
  "request": null,
  "message": null,
  "result": {
    "jobInfo": {
      "workflowId": "c868de5e-0757-3eb6-8ba3-efc6d6518707",
      "runId": "23E4QoIuGV0U39tDUFZYhU4qe8p17HvzhPJgwA+x5c3ag=",
      "downloadUrl": "https://analytics-api.app.lithium.com/api/public/reports/report/c868de5e-0757-3eb6-8ba3-efc6d6518707/23E4QoIuGV0U39tDUFZYhU4qe8p17HvzhPJgwA%2Bx5c3ag%3D/download?analyticsAccessToken=X82dojqexTsYkN9OuIBhxw%3D%3D",
      "statusUrl": "https://analytics-api.app.lithium.com/api/public/reports/report/c868de5e-0757-3eb6-8ba3-efc6d6518707/23E4QoIuGV0U39tDUFZYhU4qe8p17HvzhPJgwA%2Bx5c3ag%3D/status?analyticsAccessToken=X82dojqexTsYkN9OuIBhxw%3D%3D"
    },
    "result": {
      "runnerState": "CLOSED",
      "reason": null,
      "detail": "COMPLETED",
      "currentCount": null,
      "totalCount": null,
      "lastAcknowledgeTime": null
    }
  }
}

Once the runnerState is CLOSED, if the ‘detail field reads COMPLETED you can use the downloadURL to download the export. At this, point you are ready to run the next export.”

Optimizing Export Speed

To optimize for speed of getting your exports to complete, you can reduce the amount of data you are asking for. For example:

Agent States, User & Team Performance Exports

• Filter by Team
• Reduce time range
  Combined Export
• Instead use: Incoming Post, Response, and Conversation Export(s)
• Reduce the time range
  Incoming Post, Responses & Conversations Exports
• Filter by Workqueue or Smart View
• Reduce time range