Fundamentals

Getting started

Setup

Integrations

All integrations

Strategies

All strategies

Security

Troubleshooting

Compliance

Data Platform

Data Onboarding

Data Specification

Data Types

Attributes catalog

Data Management

Developer API

Forms

Javascript Tag

Insights

Segment

Compare

Track

Activity

Listen

Visualize

Engagement

Activate

Contact

Respond

Schedule

Serve

Activity API

Learn how to access your team performance data using our Activity API

Lexer's Activity API allows you to query and export team performance and conversation data to automate your reporting. Our API supports two types of requests; Get and Post requests.

Get requests allow you to access the user, groups and forms data.
Post requests allow you to run queries to return team and conversation data.

Authentication with API Tokens

You can find detailed instructions about how to set up an API Token in our Authentication and API token creation article. Make sure you select the Activity API Type when generating a token. If using it for the Activity API.

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.

curl -H "Content-Type: application/json" -H "Auth-Api-Token: <TOKEN>" -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	The unique user id for this user	number
email	The email address used to log in	string
first_name	The first name of the user	string
last_name	The last name of the user	string
timezone	Timezone location of user	string
gmtoffset	Timezone offset of user	Number
sign_in_count	Total count of logins	Number
last_sign_in_at	Date of users last login	Date time
archived	Flag to indicated if the user is archived	Boolean
groups	List of groups the user belongs to	Array

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.

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	Unique identifier of the group	Number
name	Name of the group	String
comment	Description of the group	String

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

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": true,
    "form_url": "https://d1z1wrkt4y2iqm.cloudfront.net/123455678899876543/1/form"
  }

Property	Description	Type
id	Unique identifier of the form	Number
name	Name of the form	String
title	Title of the form	String
archived	Flag to determine if form is archived	Boolean
created_at	Date this form was created	Date
groups	List of groups that have access to this form	Array
nps	Flag to confirm if NPS type	Boolean
form_url	URL to view this form	String

Summary Metrics

Access the summary metrics that are used to power the 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:<TOKEN>" 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

States Volume

Daily volume of messages in each workflow state. Your response will contain an array for each state, and within that state a message for each period (i.e. each day). If your query range is less than 4 days the time intervals will be reduced from days to hours.

curl -H "Content-Type: application/json" -H "Auth-Api-Token: <TOKEN>" 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 name	String
value	Number of messages in this state for this period	Number
date_range	Date of this period	String

Workflow States

Total volume of messages in each of the workflow states.

curl -H "Content-Type: application/json" -H "Auth-Api-Token: <TOKEN>" 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 Summary

Return the performance metrics for each agent in your team. The data you access in this request is used to populate the ‘Team Performance’ 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

Team 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

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

Case CSV Export

Export a CSV file containing a row for every case your team has actioned within the defined date range. More information about the Cases file can be found here. 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": "case_details", "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 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

curl <CSV File Location>

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

NPS CSV Export

Export the complete list of NPS submissions to CSV. 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: <API TOKEN>" https://api.lexer.io/v1/activity/reports -d ' { "type": "nps_submissions", "date_from": "2019-06-15T00:00:00+11:00", "date_to": "2019-06-30T23:59:59+11:00","nps_category":"all", "form":<FORM ID>}'

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: <API TOKEN>' '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>

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.

That's a wrap

That's it for our Activity API! If you get stuck, try following the steps above and please don't hesitate to reach out to Lexer Support using the chatbot in the bottom right of the page.

Updated:

October 12, 2023