Skip to Content
Administrators & Analysts
Analytics API
For more information about Mavenoid analytics, see Understand analytics.
The analytics API is currently in BETA. Please share any suggestions for improvements through this form.
Using the API
Authentication
Every request to Mavenoid's Analytics API must be authenticated using a bearer token. To obtain a token, please contact your Mavenoid representative or email [email protected].
To authenticate your API requests, include the following header with your token in place of {{ACCESS_TOKEN}}:
Authorization: Bearer {{ACCESS_TOKEN}}
Here's an example authenticated API call using curl:
curl \
-H "Authorization: Bearer ma_15prljrk6_uvsb2u6aknvutrr6cvtu9t43odabsdd0o2vg" \
"https://analytics-api.mavenoid.com/v1/assistant-conversations.json?days=30"
Rate limits
Requests for data within the last 24 hours (i.e., the days parameter is set to 1) are limited to 60 per minute.
All other requests are limited to 10 per minute.
To ensure your request is tracked properly, put the days parameter last.
Testing
For ease of testing, we provide a Postman collection: Mavenoid-Analytics-API.postman_collection.json
This collection includes sample calls for all the endpoints discussed on this page. To use it, import it into Postman and replace the Bearer token with your own (Mavenoid Analytics API → Authorization, replace the displayed Token with your own, and then save your changes).
If you don't change the bearer token, you’ll get dummy data rather than your organization's actual data.
Assistant conversations
The assistant conversations endpoint returns data about all assistant conversations for a selected period of up to 120 days. If a conversation involved any live chats, the data includes the latest live support session's status and the agent's resolution label.
A conversation occurs when a user opens the Mavenoid assistant and interacts with it in a meaningful way. If the assistant is embedded in a website or mobile app, this requires clicking/tapping a button (on a node that does not have "Step is triage" checked) or performing a search. If the assistant is in a Dynamic Help Center, where solution nodes may be presented as the result of an internet search, leaving the page open for ten seconds (on a non-autogenerated page) also counts as an interaction.
If the user opens the assistant but does not interact with it or visits a Dynamic Help Center page and closes it within ten seconds without interacting, this is considered a "bounce" and is not counted or tracked as a conversation.
Individual conversations
To retrieve all data for each individual conversation within the selected period, make the request without using the group_by parameter.
Endpoint
GET https://analytics-api.mavenoid.com/v1/assistant-conversations.json
Required parameters
days
An integer between 1 and 120 (inclusive).
How many days of data to fetch. Here a day is a period of 24 hours rather than a calendar day. If you set days=1 that will fetch the last 24 hours of data rather than the data for the current calendar day.
Response
A JSON Array where each record in the array has this schema:
interface AssistantConversation {
id: string
created_at: string // ISO8601 Timestamp
updated_at: string // ISO8601 Timestamp
flow_name: string
touchpoint_name: string // This feature is still in private beta testing
status:
| "OPEN"
| "RESOLVED"
| "ESCALATED"
label: string // The label, if set by a SetAnalyticsStatus node, otherwise the empty string
lang_code: string
latest_search_query: string | null // The search query the user typed, if any
latest_search_result_chosen: string | null // The label of the result chosen, if any
latest_search_shortcut_chosen: string | null // The label of the shortcut chosen, if any
latest_live_support_session_status:
| "WAITING_FOR_AGENT"
| "ACTIVE"
| "AGENT_TIMEOUT"
| "CUSTOMER_SKIPPED"
| "DECLINED_BY_AGENT"
| "INACTIVITY_TIMEOUT"
| "NO_AGENT_CAPACITY"
| "RESOLVED"
| null
latest_live_support_session_resolution_label: string | null
feedback_topics: string[] // Array of topics chosen by the user at the end of the session
feedback_comments: string // Feedback entered by the user at the end of the session
feedback_rating: 1 | 2 | 3 | 4 | null
form_data: Record<string, JSON>
}
Examples
Request
Get all assistant conversations from the past 30 days:
GET https://analytics-api.mavenoid.com/v1/assistant-conversations.json?days=30
Response
[
{
"id": "F1246",
"created_at": "2023-05-03T10:59:03.000Z",
"updated_at": "2023-05-03T11:02:10.000Z",
"flow_name": "Scooter Support",
"touchpoint_name": "Support Website",
"status": "RESOLVED",
"label": "",
"lang_code": "en",
"latest_search_query": "End my ride",
"latest_search_result_chosen": "How do I end my ride?",
"latest_search_shortcut_chosen": null,
"latest_live_support_session_status": null,
"latest_live_support_session_resolution_label": null,
"feedback_topics": [],
"feedback_comments": "This automated assistant was really helpful",
"feedback_rating": 4,
"form_data": {
"$customer-email": "[email protected]",
"$created-on-page-url": "https://example.com/support",
"ride-end-api-response": "ok"
}
},
{
"id": "G2467",
"created_at": "2023-05-04T10:59:03.000Z",
"updated_at": "2023-05-04T11:02:10.000Z",
"flow_name": "Scooter Support",
"touchpoint_name": "Support Website",
"status": "RESOLVED",
"label": "",
"lang_code": "en",
"latest_search_query": "End my ride",
"latest_search_result_chosen": "How do I end my ride?",
"latest_search_shortcut_chosen": null,
"latest_live_support_session_status": null,
"latest_live_support_session_resolution_label": null,
"feedback_topics": [],
"feedback_comments": "Solved my problem",
"feedback_rating": 4,
"form_data": {
"$customer-email": "[email protected]",
"$created-on-page-url": "https://example.com/support",
"ride-end-api-response": "ok"
}
},
]
Conversation summaries
To retrieve summary data including counts of conversations within the selected period grouped by particular criteria, use the group_by parameter in the request.
Endpoint
GET https://analytics-api.mavenoid.com/v1/assistant-conversations.json
Required parameters
days
An integer between 1 and 120 (inclusive).
How many days of data to fetch. Here a day is a period of 24 hours rather than a calendar day. If you set days=1 that will fetch the last 24 hours of data rather than the data for the current calendar day.
group_by
A comma-separated list of fields by which to group data.
Available fields:
dateweekmonthflow_nametouchpoint_name(This feature is still in private beta testing)statuslabellang_codelatest_live_support_session_statuslatest_live_support_session_resolution_labelfeedback_rating
Response
A JSON Array where each record in the array contains the fields by which that record is grouped and the count of conversations that occurred in that group.
Grouping by any of date, week, or month will result in the response including the date field in each record, formatted as yyyy-mm-dd. If grouping by date this will be that day's date; if grouping by week it will be the Monday of that week; if grouping by month it will be the first of that month.
Examples
Request
Get the counts of conversations for each combination of flow and status for the past 24 hours.
GET https://analytics-api.mavenoid.com/v1/assistant-conversations.json?group_by=flow_name,status&days=1
Response
[
{
"flow_name": "Scooter Support",
"status": "self_service_resolution",
"count": 512
},
{
"flow_name": "Scooter Support",
"status": "live_support_resolution",
"count": 256
},
{
"flow_name": "Scooter Support",
"status": "escalated",
"count": 128
},
{
"flow_name": "Washing Machine Support",
"status": "self_service_resolution",
"count": 1024
},
{
"flow_name": "Washing Machine Support",
"status": "live_support_resolution",
"count": 64
},
{
"flow_name": "Washing Machine Support",
"status": "escalated",
"count": 32
}
]
Live support sessions
The live support sessions endpoint returns data about all live support sessions for a selected period of up to 120 days.
Individual sessions
To retrieve all data for each individual session within the selected period, make the request without using the group_by parameter.
Endpoint
GET https://analytics-api.mavenoid.com/v1/live-support-sessions.json
Required parameters
days
An integer between 1 and 120 (inclusive).
How many days of data to fetch. Here a day is a period of 24 hours rather than a calendar day. If you set days=1 that will fetch the last 24 hours of data rather than the data for the current calendar day.
Response
A JSON Array where each record in the array has this schema:
interface LiveSupportSession {
assistant_conversation_id: string
assistant_conversation_created_at: string // ISO8601 Timestamp
created_at: string // ISO8601 Timestamp
updated_at: string // ISO8601 Timestamp
agent_email: string | null
agent_group_name: string | null
queue_duration_ms: number // The time between the end user starting the session, and an agent accepting the conversation
first_response_ms: number // The time between the end user starting the session, and the first message from an agent
chat_duration_ms: number // The time between the end user starting the session, and the agent ending it
status:
| "WAITING_FOR_AGENT"
| "ACTIVE"
| "AGENT_TIMEOUT"
| "CUSTOMER_SKIPPED"
| "DECLINED_BY_AGENT"
| "INACTIVITY_TIMEOUT"
| "NO_AGENT_CAPACITY"
| "RESOLVED"
| "TRANSFERRED"
resolution_label: string | null // custom resolutions can be added in the model
debrief_labels: string[] // Array of labels chosen by agent after the session ends
debrief_summary: string // Summary entered by agent after the session ends
feedback_rating: 1 | 2 | 3 | 4 | null // The feedback rating the end user gave to the assistant conversation that this live support session belongs to
}
Examples
Request
Get all live support sessions from the past 30 days:
GET https://analytics-api.mavenoid.com/v1/live-support-sessions.json?days=30
Response
[
{
"assistant_conversation_id": "F54321",
"assistant_conversation_created_at": "2023-05-03T15:02:10.000Z",
"created_at": "2023-05-03T15:03:00.000Z",
"updated_at": "2023-05-03T15:08:00.000Z",
"agent_email": "[email protected]",
"agent_group_name": "Europe",
"queue_duration_ms": 30000,
"chat_duration_ms": 300000,
"status": "RESOLVED",
"resolution": "worked",
"debrief_labels": ["scooter_breakdown"],
"debrief_summary": "The scooter was broken and I had to order replacement parts for the customer"
},
{
"assistant_conversation_id": "G65432",
"assistant_conversation_created_at": "2023-05-04T15:02:10.000Z",
"created_at": "2023-05-04T15:03:00.000Z",
"updated_at": "2023-05-04T15:08:00.000Z",
"agent_email": "[email protected]",
"agent_group_name": "Europe",
"queue_duration_ms": 30000,
"chat_duration_ms": 300000,
"status": "RESOLVED",
"resolution": "worked",
"debrief_labels": ["ride_refund"],
"debrief_summary": "Ride refund issues for customer"
},
]
Session summaries
To retrieve summary data including the count and aggregate statistics of sessions within the selected period grouped by particular criteria, use the group_by parameter in the request.
Endpoint
GET https://analytics-api.mavenoid.com/v1/live-support-sessions.json
Required parameters
days
An integer between 1 and 120 (inclusive).
How many days of data to fetch. Here a day is a period of 24 hours rather than a calendar day. If you set days=1 that will fetch the last 24 hours of data rather than the data for the current calendar day.
group_by
A comma-separated list of fields to group data by to generate a summary.
Available fields:
dateweekmonthagent_emailagent_group_namestatusresolution_labelfeedback_rating
Response
A JSON Array where each record in the array contains the fields by which that record is grouped and the count of and statistics for sessions that occurred in that group.
Grouping by any of date, week, or month will result in the response including the date field in each record, formatted as yyyy-mm-dd. If grouping by date this will be that day's date; if grouping by week it will be the Monday of that week; if grouping by month it will be the first of that month.
The statistics for each group are:
queue_duration_ms_maxqueue_duration_ms_meanqueue_duration_ms_sumfirst_response_ms_maxfirst_response_ms_meanfirst_response_ms_sumchat_duration_ms_maxchat_duration_ms_meanchat_duration_ms_sum
Examples
Request
Get counts and statistics for the sessions went to each agent on each day for the past 48 hours:
GET https://analytics-api.mavenoid.com/v1/live-support-sessions.json?group_by=date,agent_email&days=2
Response
[
{
"date": "2023-05-03",
"agent_email": "[email protected]",
"count": 256,
"queue_duration_ms_max": 40000,
"queue_duration_ms_mean": 30000,
"queue_duration_ms_sum": 7680000,
"first_response_ms_max": 41000,
"first_response_ms_mean": 31000,
"first_response_ms_sum": 7780000,
"chat_duration_ms_max": 400000,
"chat_duration_ms_mean": 300000,
"chat_duration_ms_sum": 76800000
},
{
"date": "2023-05-02",
"agent_email": "[email protected]",
"count": 300,
"queue_duration_ms_max": 40000,
"queue_duration_ms_mean": 30000,
"queue_duration_ms_sum": 9000000,
"first_response_ms_max": 41000,
"first_response_ms_mean": 31000,
"first_response_ms_sum": 7780000,
"chat_duration_ms_max": 400000,
"chat_duration_ms_mean": 300000,
"chat_duration_ms_sum": 90000000
}
]
Agent availability
The agent availability endpoint returns data about the times when each agent was available in the agent dashboard for a selected period of up to 120 days.
Individual availability periods
To retrieve all data for each individual availability period within the selected period, make the request without using the group_by parameter.
Endpoint
GET https://analytics-api.mavenoid.com/v1/agent-availabilities.json
Required parameters
days
An integer between 1 and 120 (inclusive).
How many days of data to fetch. Here a day is a period of 24 hours rather than a calendar day. If you set days=1 that will fetch the last 24 hours of data rather than the data for the current calendar day.
Response
A JSON Array where each record in the array has this schema:
interface AgentAvailability {
agent_email: string
start_timestamp: string // ISO8601 Timestamp
end_timestamp: string | null // ISO8601 Timestamp or null if agent is currently available
duration_ms: number // How long was the agent marked as available for
active_duration_ms: number // How long was the agent active in one or more session
}
Examples
Request
Get all agent availability information from the past 30 days:
GET https://analytics-api.mavenoid.com/v1/agent-availabilities.json?days=30
Response
[
{
"agent_email": "[email protected]",
"start_timestamp": "2023-05-03T9:00:00.000Z",
"end_timestamp": "2023-05-03T17:00:00.000Z",
"duration_ms": 28800000,
"active_duration_ms": 28000000
},
{
"agent_email": "[email protected]",
"start_timestamp": "2023-05-04T9:00:00.000Z",
"end_timestamp": "2023-05-04T17:00:00.000Z",
"duration_ms": 28800000,
"active_duration_ms": 28000000
}
]
Availability summaries
To retrieve summary data of availability periods within the selected period grouped by particular criteria, use the group_by parameter in the request.
Endpoint
GET https://analytics-api.mavenoid.com/v1/agent-availabilities.json
Required parameters
days
An integer between 1 and 120 (inclusive).
How many days of data to fetch. Here a day is a period of 24 hours rather than a calendar day. If you set days=1 that will fetch the last 24 hours of data rather than the data for the current calendar day.
group_by
A comma-separated list of fields to group data by to generate a summary.
Available fields:
dateweekmonthagent-email
Response
A JSON Array where each record in the array contains the fields by which that record is groups and the statistics for that group.
Grouping by any of date, week, or month will result in the response including the date field in each record, formatted as yyyy-mm-dd. If grouping by date this will be that day's date; if grouping by week it will be the Monday of that week; if grouping by month it will be the first of that month.
The statistics for reach record are:
agent_count(if not grouping byagent_email)duration_ms_sumactive_duration_ms_sum
Examples
Request
Get statistics for each agent's availability by date for the past 48 hours:
GET https://analytics-api.mavenoid.com/v1/agent-availabilities.json?group_by=date,agent_email&days=2
Response
[
{
"date": "2023-05-03",
"agent_email": "[email protected]",
"duration_ms_sum": 28800000,
"active_duration_ms_sum": 28000000
},
{
"date": "2023-05-02",
"agent_email": "[email protected]",
"duration_ms_sum": 28800000,
"active_duration_ms_sum": 28000000
}
]
Request
Get statistics for total agent availability by date for the past 48 hours:
GET https://analytics-api.mavenoid.com/v1/agent-availabilities.json?group_by=date&days=2
Response
[
{
"date": "2023-05-03",
"agent_count": 2,
"duration_ms_sum": 28800000,
"active_duration_ms_sum": 28000000
},
{
"date": "2023-05-02",
"agent_count": 2,
"duration_ms_sum": 28800000,
"active_duration_ms_sum": 28000000
}
]