Sessions Jobs Endpoints
These endpoints allow exporting session details which contain data on interactions of an end-user with the Solvvy interface. A session generally lasts for up to 1 hour except when the Solvvy interface is left open and interacted with later and then the session can extend beyond an hour.
This sessions jobs API allows submitting jobs to request a CSV or JSON file export of sessions for a specified date range. The jobs can be checked for their status and percent completion (e.g. polled every 1 minute). When a job is complete the resulting CSV or JSON result file can be downloaded. Jobs usually complete within a few minutes to a couple hours depending on the date range requested.
Jobs and their result files are automatically deleted after 7 days. The job export result files will also show up for manual download in the Dashboard > Data Download page under the user "Analytics API".
Create Job Endpoint
Submit a new job to export session data for a specified date range.
Request
POST /v1/analytics/sessions/jobs
Request body JSON properties:
org_id
: number (required) - the Solvvy Org ID that the request applies tostart_at
: ISO 8601 date/time string (required) - the start of the date range for which to export sessionsend_at
: ISO 8601 date/time string (required) - the exclusive end of the date range for which to export sessions. Sessions will be included if they are created within the specified range. They may have lasted past the end of the range.export_params
format
: stringcsv
(default) orjson
- The format of the export result filesort_direction
: stringdesc
(default) orasc
- The order of the sessions by creation time in the export result file. The default ofdesc
means that the first session in the file will be the most recently created.
Note that a Content-Type: application/json
request header should be included.
Example to request an export of sessions from the 1st week of July to a JSON file with the default sort (descending creation time).
{
"org_id": 4,
"start_at": "2020-07-01T00:00:00.000Z",
"end_at": "2020-07-08T00:00:00.000Z",
"export_params": {
"format": "json"
}
}
Full Curl Example:
curl -X POST \
https://api.solvvy.com/v1/analytics/sessions/jobs?org_id=4 \
-H 'X-Api-Key: 6b7f5113-f2e1-4df4-b440-65y7242b412d~iS9sVF335pQwTuVC3PeBIb55M4YF5jXyqBcA14G7zJ62e1d92dNnk3ch9WsJ86gp' \
-H 'Content-Type: application/json' \
-d '{
"org_id": 4,
"start_at": "2020-07-01T00:00:00.000Z",
"end_at": "2020-07-08T00:00:00.000Z",
"export_params": {
"format": "json"
}
}'
Response
The response is an object that contains the details of the newly submitted job. In addition to the fields sent in the request above it will include:
id
: string - the ID of the newly submitted jobuser_full_name
: string - the name of the user that submitted the request (if requested via the Dashboard Data Download page) orAnalytics API
if requested from this API.created_at
: ISO 8601 date/time string (in UTC) - the timestamp of when the job was created (submitted)updated_at
: ISO 8601 date/time string (in UTC) - the timestamp of when the job was last updatedstatus
: string - The status of the job. The initial status will always bepending
.
Example Response:
{
"id": "3b52a3b0-c571-471f-b659-b8941e6460aa",
"org_id": 4,
"start_at": "2020-07-01T00:00:00.000Z",
"end_at": "2020-07-08T00:00:00.000Z",
"export_params": {
"format": "json"
},
"user_full_name": "Analytics API",
"created_at": "2020-08-10T20:11:46.806Z",
"updated_at": "2020-08-10T20:11:46.806Z",
"status": "pending"
}
Get Job Endpoint
Get the details of a previously submitted job. It is expected this endpoint may be polled (e.g. every 1 minute) to check the status of the job. Once the job status changes to complete
then the job result can be downloaded using the Download Job Result
endpoint documented below.
Request
GET /v1/analytics/sessions/jobs/{JOB_ID}?org_id={ORG_ID}
Request path variables:
JOB_ID
: string (required) - the ID of the job to get the details for (this can be found in theid
response body property when creating a new job)
Request query parameters:
org_id
: number (required) - the Solvvy Org ID that the request applies to
Full Curl Example:
curl -X GET \
https://api.solvvy.com/v1/analytics/sessions/jobs/3b52a3b0-c571-471f-b659-b8941e6460aa?org_id=4 \
-H 'X-Api-Key: 6b7f5113-f2e1-4df4-b440-65y7242b412d~iS9sVF335pQwTuVC3PeBIb55M4YF5jXyqBcA14G7zJ62e1d92dNnk3ch9WsJ86gp'
Response
The response is an object that contains the details of the newly submitted job. In addition to the fields sent in the request above it will include:
id
: string - the ID of the newly submitted joborg_id
: number - the org ID the job was submitted forstart_at
: ISO 8601 date/time string (required) - the start of the date rangeend_at
: ISO 8601 date/time string (required) - the exclusive end of the date rangeexport_params
format
: stringcsv
orjson
- The format of the export result filesort_direction
: stringdesc
orasc
- The order of the sessions by creation time in the export result file (if different than the default)
user_full_name
: string - the name of the user that submitted the request (if requested via the Dashboard Data Download page) orAnalytics API
if requested from this API.created_at
: ISO 8601 date/time string (in UTC) - the timestamp of when the job was created (submitted)updated_at
: ISO 8601 date/time string (in UTC) - the timestamp of when the job was last updatedstatus
: string - The status of the job. The initial status will always bepending
. After the job starts (usually immediately) the status will beprocessing
. The job status will becomplete
when the job is complete and the export result file ready to download.percent_complete
: number - once the job has started this will be updated with the rough percentage completion (e.g. 33 means 33% complete)size
: number - the compressed size in bytes of the export file (gzip compression is automatically enabled for download). Only available after the job has completed.uncompressed_size
: number - the size in bytes of the uncompressed file after being downloaded and uncompressed (decompression usually happens automatically in the HTTP client). Only available after the job has completed.
Example Response:
{
"id": "3b52a3b0-c571-471f-b659-b8941e6460aa",
"org_id": 4,
"start_at": "2020-07-01T00:00:00.000Z",
"end_at": "2020-07-08T00:00:00.000Z",
"export_params": {
"format": "json"
},
"user_full_name": "Analytics API",
"percent_complete": 100,
"size": 1976732,
"uncompressed_size": 9915408,
"created_at": "2020-08-10T20:11:46.806Z",
"updated_at": "2020-08-10T20:11:46.806Z",
"status": "complete"
}
Download Job Result Endpoint
Download the export job result file that contains the sessions details for the specified date range. If this API is called before a job is complete it will return a 400 error status. The Get Job
endpoint documented above should be used first (e.g. polled every 1 minute) to confirm the job status is complete
before attempting to call this download endpoint.
Request
GET /v1/analytics/sessions/jobs/{JOB_ID}/download?org_id={ORG_ID}
Request path variables:
JOB_ID
: string (required) - the ID of the job to download the result for (this can be found in theid
response body property when creating a new job)
Request query parameters:
org_id
: number (required) - the Solvvy Org ID that the request applies to
Full Curl Example:
curl -O -X GET \
https://api.solvvy.com/v1/analytics/sessions/jobs/3b52a3b0-c571-471f-b659-b8941e6460aa/download?org_id=4 \
-H 'X-Api-Key: 6b7f5113-f2e1-4df4-b440-65y7242b412d~iS9sVF335pQwTuVC3PeBIb55M4YF5jXyqBcA14G7zJ62e1d92dNnk3ch9WsJ86gp'
Response
The response will be a redirect to a Google Cloud Storage (GCS) hosted file (using a "Signed URL" for security). Most HTTP clients will automatically follow the redirect. The resulting downloaded file will either be a CSV or JSON format depending on what was requested.
Jobs and their result files are automatically deleted after 7 days.
Response data includes:
id
: string - user session IDcreated_at
: ISO 8601 date/time string (in UTC) - date the session was createddescription
: string - user query (related to description field in ticket submission)self_serviced
: boolean - whether the session led to a deflectiondrop_off_workflows
: boolean - whether the workflow engaged (if any) led to a user exiting before reaching support or an exitversion
: string - Solvvy version (e.g.5.35.0
)browser_with_version
: string - e.g.Firefox 91
device
: string - mobile or desktopos
: string - e.g.Windows 8.1
support_flow_launched_url
: string - url where user launched Solvvysupport_flow_launched_originator
: string - How the user launched Solvvy (link
,widget
, orauto
)selected_support_option
: string - support option selected by user after unsuccessful deflection (e.g.ticket
,chat
, etc.)solution_source_urls
: array of strings - help center article linked within the returned solutions after a user queryexternal_ticket_id
: string - ID of ticket submitted through Solvvy, if any, which matches the ticket ID within the client CRMannouncement_shown
: boolean - whether the user saw an announcement within Solvvy (configurable within the Solvvy Dashboard)announcement_link_clicked
: boolean - whether the user clicked the link within the announcement, if available)workflows_shown
: boolean - whether the user was presented with one or more workflowsworkflows_engaged
: boolean - whether the user selected a workflow after being presented with the option(s)extra_metadata
: string or array of strings - can be returned multiple times with different paths. For example, the same response can contain:"extra_metadata.workflow_engaged.workflow_id as \"Intent Chosen\"": "4274da4a-5d1e-4ad8-8d45-3fc5b909fc66"
"extra_metadata.workflow_event.workflow_event_name as \"Workflow Last Action\"": "contact_support"
"extra_metadata.all:workflow_event.screen_id as \"Workflow Screens Shown\"": ["a83061a0-ac07-43ff-b7db-405f2ab02496", "a83073a0-ac07-43ff-b7db-405f2ab02496", "4520258b-6808-4393-9e0f-60744427d66c"]
Sample Code
Node.js
Example node.js program that uses axios to download the sessions from the previous 24 hours.
const axios = require('axios');
// Replace these with values from the Dashboard > Settings page
const orgId = 4;
const analyticsApiKey = '6b7f5113-f2e1-4df4-b440-65y7242b412d~iS9sVF335pQwTuVC3PeBIb55M4YF5jXyqBcA14G7zJ62e1d92dNnk3ch9WsJ86gp';
// download sessions from last 24 hours
const now = new Date();
const startAt = new Date(now.getTime() - 24 * 60 * 60 * 1000);
const endAt = now;
// allow up to 1 hour to wait for job completion (may need to increase for large ranges)
const maxWaitSeconds = 1 * 60 * 60;
const analyticsApi = axios.create({
baseURL: 'https://api.solvvy.com/v1/analytics'
headers: { 'x-api-key': analyticsApiKey }
});
(async () => {
let job;
console.log(`Creating job to export sessions created between ${startAt} and ${endAt}`);
// create job to export sessions for specified date range to JSON format
const createResponse = await analyticsApi.post('/sessions/jobs', {
org_id: orgId,
start_at: startAt,
end_at: endAt,
export_params: { format: 'json' }
});
job = createResponse.data;
console.log(`Created job ${job.id}`);
// setup timeout timer as safety net
const maxWaitTimer = setTimeout(() => {
throw new Error(`Max wait seconds exceeded, job not complete after ${maxWaitSeconds} seconds`);
}, maxWaitSeconds * 1000);
// wait for job to complete
while (job.status !== 'complete') {
console.log(`Job not finished yet (${job.percent_complete || 0}% complete), waiting...`);
// wait 30s between checks
await new Promise((resolve) => setTimeout(resolve, 30 * 1000));
const getResponse = await analyticsApi.get(`/sessions/jobs/${job.id}?org_id=${orgId}`);
job = getResponse.data;
}
clearTimeout(maxWaitTimer);
console.log(`Job complete, downloading result file of size ${job.size} bytes...`);
// download job result
const downloadResponse = await analyticsApi.get(`/sessions/jobs/${job.id}/download?org_id=${orgId}`);
const sessions = downloadResponse.data;
console.log(`${sessions.length} sessions downloaded`);
// print out queries from first few sessions to show download worked
console.log('Printing queries from first 3 sessions (most recently created)');
for (const session of sessions.slice(0, Math.min(3, sessions.length))) {
console.log(`QUERY: ${session.description}`);
}
})().catch(console.error);