Activity API
Learn how to access your team performance data via our Activity API
Activity API allows you to retrieve performance data on your team operating within Lexer Engage. Access insightful metrics such as the number of closed cases, average response time, or your overall NPS score.
Our API supports two types of requests; Get and Post requests.
- Get requests allow you to access the user, groups and forms metadata.
- Post requests allow you to run queries to return team insights
Authenticating your requests
You will need an API token to access your Activity data. API Tokens are managed within Integrate, and require Manager permissions to access and modify. All endpoints require an API token to authenticate your requests.
API tokens can only be viewed at the moment you create them, ensuring that your token is only available for the use case it was created for. If you misplace your token you can either reset the token or generate a new one.
We suggest creating a new API token for each application or use case. As rate limits are token specific, this will prevent multiple applications from impacting each other.
Retrieve users, groups and forms
GET Users
Retrieve a list of users that have access to your Lexer account. You can use these user details to filter any of the Activity queries for agent specific metrics. Here we’ll describe how you request and interpret this information.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" -X GET https://api.lexer.io/v1/users
Endpoint https://api.lexer.io/v1/users
{
"id": 12345,
"email": "jane@business.io",
"first_name": "Jane",
"last_name": "Remington",
"timezone": "Australia/Sydney",
"gmtoffset": 10,
"sign_in_count": 76,
"last_sign_in_at": "2018-03-21T06:09:01Z",
"archived": false,
"groups": [
123,
456,
789,
]
}
Property | Description | Type |
id | user id | number |
email account used to login | string | |
first_name | first name of the user | string |
last_name | last name of the user | string |
timezone | timezone location of user | string |
gmtoffset | timezone offset of user | number |
sign_in_count | count of logins | number |
last_sign_in_at | date of users last login | string |
archived | archived flag for user | boolean |
groups | groups the user is in | array |
GET Groups
Retrieve a list of groups that exist in your Lexer account. You can use these group details to filter any of the Activity queries for team specific metrics. Here we’ll describe how you request and interpret this information.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" -X GET https://api.lexer.io/v1/groups
Endpoint https://api.lexer.io/v1/groups
{
"id": 123,
"name": "Social Customer Care",
"comment": "Social customer care team members"
}
Property | Description | Type |
id | group id | number |
name | name of the group | string |
comment | description of the group | string |
GET Forms
Retrieve a list of forms/surveys that exist in your Lexer account. These include NPS surveys, authentication forms, and competition surveys. You need to specify the NPS Survey id when requesting the NPS Summary or NPS Volume data. Here we’ll describe how you request and interpret this information.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" -X GET https://api.lexer.io/v1/forms
Endpoint https://api.lexer.io/v1/forms
{
"id": 55,
"name": "NPS Survey",
"title": "Lexer NPS Survey",
"archived": false,
"created_at": "2018-05-26T21:54:19Z",
"groups": [
123
],
"nps": false,
"form_url": "https://d1z1wrkt4y2iqm.cloudfront.net/123455678899876543/1/form"
}
Property | Description | Type |
id | form id | number |
name | name of the form | string |
title | title of the form | string |
archived | archived flag | boolean |
created_at | date this form was created | string |
groups | groups that have access to this form | array |
nps | is this form an NPS survey? | boolean |
form_url | URL to view this form | string |
Summary
Access your teams high level performance metrics - including total messages handled, response times, and classifications on these messages.

Summary Metrics
Access the summary metrics that are used to power the big number metrics you can see in Activity. This includes the number of messages handled, response count, average response time, agent response time and a few others.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "summary", "date_from": "2018-04-01T00:00:00+11:00", "date_to": "2018-04-30T23:59:59+11:00" }'
Endpoint https://api.lexer.io/v1/activity/reports
Type: summary
{
"total_volume": 81,
"avg_response_time": 181795.692883103,
"avg_action_response_time": 167207.984987586,
"total_responded_to": 29,
"broke_sla": 11,
"broke_action_sla": 10,
"min_response_time": 34.090906,
"median_response_time": 649.951914,
"max_response_time": 1387160.862218,
"min_action_response_time": 5.63089,
"median_action_response_time": 96.865511,
"max_action_response_time": 1387064.010109,
"avg_action_response_time_min": 2786.7997497931,
"avg_response_time_min": 3029.9282147183835,
"median_action_response_time_min": 1.6144251833333334,
"median_response_time_min": 10.8325319
}
Property | Description | Type |
total_volume | total messages handled | number |
total_responded_to | messages responded to | number |
broke_sla | number of messages that exceeded customer SLA time | number |
broke_action_sla | number of messages that exceeded agent handle SLA time | number |
min_response_time | min customer wait time in seconds | number |
max_response_time | max customer wait time in seconds | number |
min_action_response_time | min agent response time in seconds | number |
max_action_response_time | max agent response time in seconds | number |
median_response_time | median customer wait time in seconds | number |
median_response_time_min | median customer wait time in minutes | number |
median_action_response_time | median agent response time in seconds | number |
median_action_response_time_min | median agent response time in minutes | number |
avg_response_time | average customer wait time in seconds | number |
avg_action_response_time | average agent response time in seconds | number |
avg_response_time_min | average customer wait time time in minutes | number |
avg_action_response_time_min | average agent response time in minutes | number |
Summary Volume
Daily volume of messages in each workflow state. Your response will contain an array for each state, and within that state an message for each period (i.e. each day).
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "states_volume", "date_from": "2018-04-01T00:00:00+11:00", "date_to": "2018-04-30T23:59:59+11:00" }'
Endpoint https://api.lexer.io/v1/activity/reports
Type: states_volume
{
"closed": [
{
"state": "closed",
"value": 174,
"date_range": {
"date_from": "2018-04-27 00:00"
}
},
{
"state": "closed",
"value": 234,
"date_range": {
"date_from": "2018-04-28 00:00"
}
},
{
"state": "closed",
"value": 255,
"date_range": {
"date_from": "2018-04-29 00:00"
}
},
{
"state": "closed",
"value": 108,
"date_range": {
"date_from": "2018-04-30 00:00"
}
}
]
}
Property | Description | Type |
state | workflow state | string |
value | number of messages in this state | number |
date_range | date for value | string |
Notes: If your query range is less than 4 days the time intervals will be reduced from days to hours.
States
Total volume of messages in each of the workflow states.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "user_volume", "date_from": "2018-04-01T00:00:00+11:00", "date_to": "2018-04-30T23:59:59+11:00" }'
Endpoint https://api.lexer.io/v1/activity/reports
Type: user_volume
[
{
"state": "closed",
"volume": 92
},
{
"state": "responded",
"volume": 49
},
{
"state": "assigned",
"volume": 26
},
{
"state": "in_progress",
"volume": 13
},
{
"state": "duplicate",
"volume": 4
},
{
"state": "awaiting_approval",
"volume": 1
}
]
Property | Description | Type |
state | workflow state | string |
volume | count of messages | number |
Classifications (Messages)
Classifications and the number of messages in each workflow state. You can get the total count for each classification using the ‘all_states’ value for the state field.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "classifications", "date_from": "2018-04-01T00:00:00+11:00", "date_to": "2018-04-30T23:59:59+11:00" }'
Endpoint https://api.lexer.io/v1/activity/reports
Type: classifications
[
{
"classification_id": 123,
"classification": "amusing",
"state": "assigned",
"volume": 2
},
{
"classification_id": 123,
"classification": "amusing",
"state": "all_states",
"volume": 3
},
{
"classification_id": 123,
"classification": "amusing",
"state": "closed",
"volume": 1
},
{
"classification_id": 143,
"classification": "customer service",
"state": "responded",
"volume": 1
},
{
"classification_id": 143,
"classification": "customer service",
"state": "all_states",
"volume": 1
}
]
Property | Description | Type |
classification_id | unique id | number |
classification | name | string |
state | workflow state | string |
volume | count of classifications | number |
Response Time
Returns the daily average response time for all messages handled by your team. Here we’re looking at the same data that powers the SLA Performance line chat in Activity. Note that if your query range is 3 days or less, the intervals will be reduced to hourly.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "response_volume", "date_from": "2018-04-01T00:00:00+11:00", "date_to": "2018-04-30T23:59:59+11:00" }'
Endpoint https://api.lexer.io/v1/activity/reports
Type: response_volume
{
"avg_response_time": [
{
"value": 317691.388907962,
"date_range": {
"date_from": "2018-06-05 00:00"
}
},
{
"value": 31159.3797606667,
"date_range": {
"date_from": "2018-06-06 00:00"
}
},
{
"value": 69850.8753626667,
"date_range": {
"date_from": "2018-06-07 00:00"
}
},
{
"value": 10661.255474,
"date_range": {
"date_from": "2018-06-08 00:00"
}
}
]
}
Property | Description | Type |
value | average response time in minutes | number |
date_range | date interval | string |
Team
Access your teams individual performance data - including messages handled per agent, response times, and more.

Agent Summary
Return the performance metrics for each agent in your team. The data you access in this request is used to populate the ‘Team’ chart in Activity.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "user_summary", "date_from": "2018-04-01T00:00:00+11:00", "date_to": "2018-04-30T23:59:59+11:00" }'
Endpoint https://api.lexer.io/v1/activity/reports
Type: user_summary
[
{
"first_name": "Jane",
"last_name": "Pear",
"mentions_assigned": 12,
"user_id": "123",
"responded_to": 9,
"responded_to_in_private": 6,
"avg_response_time": 17053.3492157778,
"min_response_time": 56.983366,
"max_response_time": 84664.420214,
"avg_action_response_time": 278.770835555556,
"min_action_response_time": 7.767898,
"max_action_response_time": 2261.353394,
"total_responded_to": 9,
"broke_sla": 3,
"broke_action_sla": 0,
"avg_response_time_min": 284.22248692962995,
"avg_action_response_time_min": 4.6461805925926,
"fraction_responded_to": 0.75,
"fraction_responded_to_in_private": 0.6666666666666666,
"fraction_broke_sla": 0.3333333333333333,
"fraction_broke_action_sla": 0.0
},
{
"first_name": "Barry",
"last_name": "Banana",
"mentions_assigned": 7,
"user_id": "789",
"responded_to": 1,
"responded_to_in_private": 1,
"avg_response_time": 352842.64921,
"min_response_time": 352842.64921,
"max_response_time": 352842.64921,
"avg_action_response_time": 134.51357,
"min_action_response_time": 134.51357,
"max_action_response_time": 134.51357,
"total_responded_to": 1,
"broke_sla": 1,
"broke_action_sla": 0,
"avg_response_time_min": 5880.710820166667,
"avg_action_response_time_min": 2.241892833333333,
"fraction_responded_to": 0.14285714285714285,
"fraction_responded_to_in_private": 1.0,
"fraction_broke_sla": 1.0,
"fraction_broke_action_sla": 0.0
}
]
Property | Description | Type |
first_name | first name of agent | string |
last_name | last name of agent | string |
mentions_assigned | count of messages assigned to agent | number |
user_id | unique id of agent | string |
responded_to | count of messages responded to | number |
responded_to_in_private | count of messages responded to that are private messages | number |
avg_response_time | average customer to reponse time in seconds | number |
min_response_time | average customer to reponse time in seconds | number |
max_response_time | max customer to reponse time in seconds | number |
avg_action_response_time | average assign to response time in seconds | type |
min_action_response_time | min assign to response time in seconds | type |
max_action_response_time | max assign to response time in seconds | type |
total_responded_to | count of messages responded to | number |
broke_sla | number of messages that exceeded customer SLA time | number |
broke_action_sla | number of messages that exceeded agent response SLA time | number |
avg_response_time_min | average customer response time in minutes | number |
avg_action_response_time_min | average agent response time in minutes | type |
fraction_responded_to | responded_to divided by mentions_assigned | number |
fraction_responded_to_in_private | responded_to_in_private divided by mentions_assigned | number |
fraction_broke_sla | broke_sla divided by responded_to | number |
fraction_broke_action_sla | broke_action_sla divided by responded_to | number |
Agent Volume
Return the count of messages currently assigned to each agent in your team. For each team member, this will also breakdown the messages by their current workflow state.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "user_volume", "date_from": "2018-04-01T00:00:00+11:00", "date_to": "2018-04-30T23:59:59+11:00" }'
Endpoint https://api.lexer.io/v1/activity/reports
Type: user_volume
[
{
"user_id": 123,
"first_name": "Jane",
"last_name": "Pear",
"states": {
"all_states": 166,
"all_closed_states": 110,
"new": 0,
"assigned": 15,
"in_progress": 14,
"responded": 27,
"awaiting_approval": 0,
"redirected": 0,
"irrelevant": 0,
"duplicate": 0,
"closed": 110,
"no_response_required": 0
}
},
{
"user_id": 789,
"first_name": "Barry",
"last_name": "Banana",
"states": {
"all_states": 4,
"all_closed_states": 1,
"new": 0,
"assigned": 1,
"in_progress": 1,
"responded": 1,
"awaiting_approval": 0,
"redirected": 0,
"irrelevant": 0,
"duplicate": 0,
"closed": 1,
"no_response_required": 0
}
}
]
Property | Description | Type |
user_id unique | id for agent | number |
first_name | first name of agent | string |
last_name | last name of agent | string |
states | count of each state owned by agent | array |
Cases
Access performance metrics on the conversations your team are having, which we call cases. This includes total case volume, first response times, resolution times, and case classifications.

Case Summary
Return the summary metrics for the cases your team have handled. Cases are only created when an agent responds to a customer.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "case_summary", "date_from": "2018-04-01T00:00:00+11:00", "date_to": "2018-04-30T23:59:59+11:00" }'
Endpoint https://api.lexer.io/v1/activity/reports
Type: case_summary
{
"total_cases": 10,
"first_reply_time": 305511.915624,
"resolution_time": 427361.668069,
"median_first_reply_time": 83991.86431,
"median_resolution_time": 310362.299289,
"agent_interactions": 2.4,
"agents_involved": 1.0
}
Property | Description | Type |
total_cases | count of cases closed in this period | number |
first_reply_time | average case first reply time in seconds | number |
resolution_time | average case resolution time in seconds | number |
median_first_reply_time | median case first reply time in seconds | number |
median_resolution_time | median case resolution time in seconds | number |
agent_interactions | average number of agent replies per case | number |
agents_involved | average number of agents responding per case | number |
Case Volume
Return the count of open cases for each day. Cases are tracked from the first customer query to the last agent response. Cases are closed 24 hours of inactivity from either the customer or the agent, provided all customer messages are in a closed state.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "case_volume", "date_from": "2018-04-01T00:00:00+11:00", "date_to": "2018-04-30T23:59:59+11:00" }'
Endpoint https://api.lexer.io/v1/activity/reports
Type: case_volume
{
"open": [
{
"value": 9,
"date_range": {
"date_from": "2018-04-01 00:00"
}
},
{
"value": 9,
"date_range": {
"date_from": "2018-04-02 00:00"
}
},
{
"value": 9,
"date_range": {
"date_from": "2018-04-03 00:00"
}
},
{
"value": 9,
"date_range": {
"date_from": "2018-04-04 00:00"
}
},
{
"value": 9,
"date_range": {
"date_from": "2018-04-05 00:00"
}
},
{
"value": 10,
"date_range": {
"date_from": "2018-04-06 00:00"
}
},
{
"value": 9,
"date_range": {
"date_from": "2018-04-07 00:00"
}
}
]
}
Property | Description | Type |
value | count of active cases | number |
date_from | date interval | string |
Case Classifications
Return the count of classifications applied to the cases in this time period. Classifications are only counted once per case, helping you understand the number of conversations about each topic.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "case_classifications", "date_from": "2018-04-01T00:00:00+11:00", "date_to": "2018-04-30T23:59:59+11:00" }'
Endpoint https://api.lexer.io/v1/activity/reports
Type: case_classifications
[
{
"classification_id": 466,
"classification": "positive",
"volume": 1
},
{
"classification_id": 526,
"classification": "social nps",
"volume": 1
},
{
"classification_id": 528,
"classification": "feedback",
"volume": 1
},
{
"classification_id": 1246,
"classification": "amusing",
"volume": 1
},
{
"classification_id": 1465,
"classification": "image",
"volume": 1
},
{
"classification_id": 1467,
"classification": "loyalty",
"volume": 1
},
{
"classification_id": 1472,
"classification": "bot",
"volume": 1
}
]
Property | Description | Type |
classification_id | unique id for each classification | number |
classification | name for each classification | string |
volume | count of classifications | number |
NPS
Access your teams NPS performance metrics - including overall score, count of detractors, promoters, passives, and your average response rate. Reminder to retrieve your forms (see GET Forms above) to retrieve a list of the NPS Surveys your team are using. The ID for your form will be used to generate the following queries.

NPS Summary
Return the summary metrics for the specified NPS Survey.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "nps_summary", "date_from": "2018-04-01T00:00:00+11:00", "date_to": "2018-04-30T23:59:59+11:00", "form": 123, "nps_category": "all" }'
Endpoint https://api.lexer.io/v1/activity/reports
Type: nps_summary
{
"total_sent": 16,
"total_received": 12,
"total_promoters": 9,
"total_passives": 1,
"total_detractors": 2,
"nps_score": 58.333333333333336
}
Property | Description | Type |
total_sent | count of surveys sent | number |
total_received | count of responses received | number |
total_promoters | count of 9-10 score responses | number |
total_passives | count of 7-8 score responses | number |
total_detractors | count of <7 score responses | number |
nps_score | average nps score | number |
NPS Volume
Return the daily volume of NPS scores and responses for each day in your query range.
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "nps_volume", "date_from": "2018-04-01T00:00:00+11:00", "date_to": "2018-04-30T23:59:59+11:00", "form": 123, "nps_category": "all" }'
Endpoint https://api.lexer.io/v1/activity/reports
Type: nps_volume
[
{
"date": "2018-04-01T13:00:00+00:00",
"timestamp": 1522587600,
"data": {
"total_sent": 0,
"total_received": 0,
"total_promoters": 0,
"total_passives": 0,
"total_detractors": 0,
"nps_score": 0.0
}
},
{
"date": "2018-04-02T13:00:00+00:00",
"timestamp": 1522674000,
"data": {
"total_sent": 0,
"total_received": 0,
"total_promoters": 0,
"total_passives": 0,
"total_detractors": 0,
"nps_score": 0.0
}
},
{
"date": "2018-04-03T13:00:00+00:00",
"timestamp": 1522760400,
"data": {
"total_sent": 0,
"total_received": 0,
"total_promoters": 0,
"total_passives": 0,
"total_detractors": 0,
"nps_score": 0.0
}
},
{
"date": "2018-04-04T13:00:00+00:00",
"timestamp": 1522846800,
"data": {
"total_sent": 0,
"total_received": 0,
"total_promoters": 0,
"total_passives": 0,
"total_detractors": 0,
"nps_score": 0.0
}
},
{
"date": "2018-04-05T13:00:00+00:00",
"timestamp": 1522933200,
"data": {
"total_sent": 0,
"total_received": 0,
"total_promoters": 0,
"total_passives": 0,
"total_detractors": 0,
"nps_score": 0.0
}
},
{
"date": "2018-04-06T13:00:00+00:00",
"timestamp": 1523019600,
"data": {
"total_sent": 0,
"total_received": 0,
"total_promoters": 0,
"total_passives": 0,
"total_detractors": 0,
"nps_score": 0.0
}
},
{
"date": "2018-04-07T13:00:00+00:00",
"timestamp": 1523106000,
"data": {
"total_sent": 0,
"total_received": 0,
"total_promoters": 0,
"total_passives": 0,
"total_detractors": 0,
"nps_score": 0.0
}
}
]
Property | Description | Type |
date | date time in UTC | string |
timestamp | date time in Epoch time | number |
total_sent | count of surveys sent | number |
total_received | count of responses received | number |
total_promoters | count of 9-10 score responses | number |
total_passives | count of 7-8 score responses | number |
total_detractors | count of <7 score responses | number |
nps_score | average nps score | number |
Responses CSV Export
You also have the ability to export the master response file to CSV for custom analysis. This is the SLA Responses file that you can export from the hub, and contains all of the messages your team have handled, including their associated interaction metadata (agent response time, customer wait time, notes etc). Accessing this file via the API is done in three steps:
- Initiate the export job
- Retrieve the CSV file location
- Download the CSV file
1. Initiate the export job
curl -H "Content-Type: application/json" -H "Auth-Api-Token: 12345678-1234-1234-1234-123456789" https://api.lexer.io/v1/activity/reports -d ' { "type": "mention_sla_export", "date_from": "2019-06-15T00:00:00+11:00", "date_to": "2019-06-30T23:59:59+11:00" }'
This will respond with the following:
{ "status": "pending", "url": null, "token": "<report_token>" }
Grab this token to use in the next step.
2. Retrieve the CSV file location
Run the following command to download the file:
curl -G -H 'Auth-Api-Token: 12345678-1234-1234-1234-123456789' 'https://clients.lexer.io/api/public/v1/activity/reports/status?token=<report_token>'
This will respond with the following when complete:
{ "status": "complete", "url": "<CSV File Location>", "token": "<report_token> }
3. Download the CSV file
Finally you run the following to download the CSV file:
curl <CSV File Location>
Errors
The API may return the following error codes.
Code | Type | Description |
400 | Invalid report - date range is too long | Your date range must be not greater than 12 months |
400 | Invalid report - starting date is a future date | Starting date must be in the past |
400 | Invalid report - invalid type | Chart type provided is invalid |
401 | Unauthorized - api token not matching | Your API token provided is not valid |
401 | Unauthorized | Missing authentication data |
404 | Not found | General error for malformed request |
429 | Rate limited exceeded | You’re making too many requests |
Rate Limiting
The API may rate limit requests made by your application. Our rate limits are managed by an allowed number of requests per time window. A single request could be to retrieve a list of users, or query a particular chart endpoint.
The rate limit is 100 requests per 5 minutes per API Token.
In the case you are rate limited a “429 Rate limited exceeded” response will be returned.