Skip to main content

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 to
  • start_at: ISO 8601 date/time string (required) - the start of the date range for which to export sessions
  • end_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: string csv (default) or json - The format of the export result file
    • sort_direction: string desc (default) or asc - The order of the sessions by creation time in the export result file. The default of desc 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 job
  • user_full_name: string - the name of the user that submitted the request (if requested via the Dashboard Data Download page) or Analytics 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 updated
  • status: string - The status of the job. The initial status will always be pending.

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 the id 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 job
  • org_id: number - the org ID the job was submitted for
  • start_at: ISO 8601 date/time string (required) - the start of the date range
  • end_at: ISO 8601 date/time string (required) - the exclusive end of the date range
  • export_params
    • format: string csv or json - The format of the export result file
    • sort_direction: string desc or asc - 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) or Analytics 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 updated
  • status: string - The status of the job. The initial status will always be pending. After the job starts (usually immediately) the status will be processing. The job status will be complete 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 the id 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 ID
  • created_at: ISO 8601 date/time string (in UTC) - date the session was created
  • description: string - user query (related to description field in ticket submission)
  • self_serviced: boolean - whether the session led to a deflection
  • drop_off_workflows: boolean - whether the workflow engaged (if any) led to a user exiting before reaching support or an exit
  • version: string - Solvvy version (e.g. 5.35.0)
  • browser_with_version: string - e.g. Firefox 91
  • device: string - mobile or desktop
  • os: string - e.g. Windows 8.1
  • support_flow_launched_url: string - url where user launched Solvvy
  • support_flow_launched_originator: string - How the user launched Solvvy (link, widget, or auto)
  • 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 query
  • external_ticket_id: string - ID of ticket submitted through Solvvy, if any, which matches the ticket ID within the client CRM
  • announcement_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 workflows
  • workflows_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);