Export Advanced Buyer Analytics via API

This brief guide will show you how to export Advanced Buyer Analytics via API.

Threekit Data Export via API

In order to export ABA data from Threekit, you'll need to follow the following steps:

  1. Query for a report. If the data has already been exported, this API will not re-generate the report.
  2. Query for the job and its results

Querying for a report

To query for a new or existing report, you will need to send a GET request to the analytics API.

let ENV = 'https://preview.threekit.com' // this will be whatever environment you are querying for data n
let ORG_ID = '1d7bc227-2ea7-434e-8281-65958b03f41b' // Your Threekit Org ID
let AUTH_TOKEN = '6cd6dbb6-86dc-4048-b542-908169b16d77' // API token
let EVENT_TYPE = 'configuration_change'

/*
    Event types:
    configuration_change
    player_loaded
    left_configurator
*/

// Dates will be formatted in YYYY-MM-DD
let START_DATE = '2024-01-01'
let END_DATE = '2024-01-19'

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("authorization", `Bearer ${AUTH_TOKEN}`);

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch(
  `${ENV}/api/analytics/report?orgId=${ORG_ID}&eventType=${EVENT_TYPE}&startDate=${START_DATE}&endDate=${END_DATE}`,
  requestOptions
)
  .then((response) => response.json())
  .then((response) => console.log(response))
  .catch((err) => console.error(err));

This will return an object containing details about the data export job. You will need the job's ID in the next step:

Querying for job results

To query for a job's results you will need the job's ID:

let ENV = "https://preview.threekit.com"; // this will be whatever environment you are querying for data n
let AUTH_TOKEN = "6cd6dbb6-86dc-4048-b542-908169b16d77"; // API token
let JOB_ID = "24fea84b-bdd1-4534-be25-93eeaa2c56af"; // This will be returned from your previous API call

const options = {
  method: "GET",
  headers: {
    accept: "application/json",
    authorization: `Bearer ${AUTH_TOKEN}`,
  },
};

fetch(`${ENV}/api/catalog/jobs/${JOB_ID}`, options)
  .then((response) => response.json())
  .then((response) => console.log(response))
  .catch((err) => console.error(err));

A successful export will return an object that contains data similar to:

 ..."output": {
    "fileId": "a716dfd2-ea2e-4d62-999c-e9c8dbeab9ab",
    "fileName": "analytics-metric_configuration_change-2024-01-01-2024-01-19--000000000000.csv.zip"
  }

Using the details in the output object, you can retrieve data about your export or download the file itself:

let fileDetailEndpoint = `${ENV}/api/files/${FILE_ID}` // this will return details about the file
let fileEndpoint = `${ENV}/api/files/${FILE_ID}/content` // this will let you download the tile itself

📘

Please note that a job may take several minutes to complete.

Prior to downloading the result, please ensure you check for the job's successful completion first, by checking for "status": "stopped" in the JSON return, and that the file output exists. You can repeat the fetch request every 5 seconds until this happens.