Skip to main content

Reporting

Sapling's API endpoint for exporting team user activity and analytics. See Team Management for getting the IDs for a particular team.

Organization Teams GET​

Request Parameters​

https://api.sapling.ai/api/v1/reporting/organization/teams

key: String
32-character API key

organization_id: String (UUID)
ID of a Sapling organization. API key holder must have manager or admin permissions for the organization.

return names: Optional Boolean
Default is false. If true, result have extra field containing team names along with the ids.

Response Parameters​

JSON array of team IDs of teams under the organization if return_names is false, else JSON array of {"id": "team_id", "name": "team_name"} entries.

User Reporting GET​

API key holder must have reporting permissions for the team.

Request Parameters​

import requests

key = '<api-key>'

url = 'https://api.sapling.ai/api/v1/reporting/team/dashboard_user_data'
data = {
    'key': key,
    'team_ids': ['<team_id1>', '<team_id2>'],
    'start_date': '2021-12-01',
    'end_date': '2021-12-08',
}

try:
    resp = requests.post(url, json=data)
    if 200 <= resp.status_code < 300:
        print(resp)
    else:
        resp_json = resp.json()
        print('Error: ', resp_json)
except Exception as e:
    print('Error: ',  e)

https://api.sapling.ai/api/v1/reporting/team/dashboard_user_data

HTTP method: POST

key: String
32-character API key

team_ids: Array of Strings (UUID)
Array of IDs of Sapling Teams.

start_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 1 year. Example: 2021-12-01 or 2021-12-01 03:29.

end_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 1 year. Example: 2021-12-08 or 2021-12-08 13:59.

If a date without time is specified (like 2021-12-08), only actions up to previous day (2021-12-07 23:59:59) will be included.

Response Parameters​

List of user reporting statistics.

If a user is part of multiple teams there will be multiple reporting structures for that user with a different team_id field value.

User Reporting Structure:

{
    "accepts":  <int>,                         // Number of Sapling edit suggestions accepted
    "completion_char_counts": <int>,           // Character count of autocompletions, for estimating time saved
    "completion_counts": <int>,                // Number of times autocompletion was used
    "hours_saved": <int>,                      // Estimate of time saved
    "id": <str, UUID>,                         // Opaque user id, used for management
    "is_admin": <bool>,                        // This allows for excluding admins from reporting
    "is_manager": <bool>,                      // This allows for excluding managers from reporting
    "login_email": <str, email>,               // Login email of user
    "mean_response_time": <int>,               // Mean agent response time in seconds
    "median_response_time": <int>,             // Median agent response time in seconds
    "rejects": <int>,                          // Number of Sapling edit suggestions rejected
    "snippet_char_counts": <int>,              // Character count of snippets used, for estimating time saved
    "snippet_counts": <int>,                   // Number of snippets used
    "suggest_helper_selects": <int, optional>, // If Sapling Suggest is enabled for team.
    "suggest_selects": <int, optional>,        // If Sapling Suggest is enabled for team
    "suggest_views": <int,  optional>,         // If Sapling Suggest is enabled for team
    "word_count": <int>,                       // Total words
    "team_id": <str, UUID>,
}

Suggest Reporting GET​

DEPRECATED

API key holder must have reporting permissions for the team. Team must have Sapling Suggest enabled.

Request Parameters​

import requests

key = '<api-key>'

url = 'https://api.sapling.ai/api/v1/reporting/team/dashboard_user_suggest_data'
data = {
    'key': key,
    'team_id': '<team_id>',
    'start_date': '2021-12-01',
    'end_date': '2021-12-08',
}

try:
    resp = requests.post(url, json=data)
    if 200 <= resp.status_code < 300:
        print(resp)
    else:
        resp_json = resp.json()
        print('Error: ', resp_json)
except Exception as e:
    print('Error: ',  e)

https://api.sapling.ai/api/v1/reporting/team/dashboard_user_suggest_data

HTTP method: POST

key: String
32-character API key

team_id: String (UUID)
ID of a Sapling team.

start_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 1 year. Example: 2021-12-01 or 2021-12-01 03:29.

end_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 1 year. Example: 2021-12-08 or 2021-12-08 13:59.

If a date without time is specified (like 2021-12-08), only actions up to previous day (2021-12-07 23:59:59) will be included.

Response Parameters​

JSON list of Sapling Suggest reporting stats.

Each item in the list has the following structure:

{
    "adjusted_views": <int>,          // Responses shown excluding ones within 4 seconds of previous
    "helper_selects": <int>,
    "id": <str, UUID>,                // Opaque user id, used for management
    "is_admin": <bool>,               // This allows for excluding admins from reporting
    "is_manager": <bool>,             // This allows for excluding managers from reporting
    "login_email": <str, email>,
    "mean_response_time": <float>,    // Mean agent response time in seconds
    "median_response_time": <float>,  // Median agent response time in seconds
    "suggest_selects": <int>,         // Number of suggested responses selected
    "suggest_views": <int>,           // Number of suggested responses shown
}

Documents Reporting GET​

API key holder must have reporting permissions for the team.

This endpoint is only applicable to enterprise teams with the Documents dashboard enabled for their team. The endpoint summarizes edit activity per document.

Request Parameters​

https://api.sapling.ai/api/v1/reporting/team/dashboard_docs_data

HTTP method: POST

key: String
32-character API key

team_id: String
ID of a Sapling team.

start_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 30 days. Example: 2021-12-01 or 2021-12-01 03:29.

end_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 30 days. Example: 2021-12-08 or 2021-12-08 13:59.

If a date without time is specified (like 2021-12-08), only actions up to previous day (2021-12-07 23:59:59) will be included.

Response Parameters​

JSON list of documents and Sapling usage information for each document.

Each item in the list has the following structure:

{
    "doc_name": <str>,         // Unique string identifying the document
    "edit_views": <int>,       // Number of edits viewed/applied
    "edit_accepts": <int>,     // Number of edits accepted in document
    "edit_ignores": <int>,     // Number of edits ignored in document
    "doc_timestamp": <int>,    // Timestamp that document was created
    "edit_users": <Array<str, emails[]>>, // Users who performed edit actions
}

API Usage POST​

This endpoint allows users to get API usage for a given time period as well as check their current quota.

Request Parameters​

https://api.sapling.ai/api/v1/reporting/api_quota_usage

HTTP method: POST

key: String
32-character API key

start_days_back: Integer
Starting number of days ago (7 would consider usage starting 1 week ago).

end_days_back: Integer
Ending number of days ago (0 would mean up until current date).

Response Parameters​

JSON structure with API usage reporting information. There may be additional metadata that is subject to change.

{
    "quota": <int>,             // Quota allocated to API key per month
    "usage": <int>,             // Usage volume during time period
    "last_updated": <float>,    // Timestamp that usage information was last updated (Unix epoch seconds)
}