Installing the cx.py Tool

Introduction

Beside the Insight UI: Custom Workspaces, which is an ideal web-based tool, this page covers how to use the underlying Insight API directly from the command line.

To get started, the easiest is to download and use the Python script cx.py. It's convenient to make the script executable and to place it somewhere in your path. The cx.py script requires Python version 2.7.6 or above + the requests library to work properly.

In case you encounter any errors during the installation, please check if there is not an expired SSL certificate on the domain cxense.com. If yes, please reach out to support@piano.io and ask them to renew the certificate.

Resources

• Examples are given throughout our documentation to document our API.

• The API emits JSON. Command-line support to post-process this JSON is available based on the Open Source command-line tool "jq" (http://stedolan.github.io/jq/).

• Advanced examples on how to use jq to create a CSV output can be found on the Working with Excel page.

Configuration

The script assumes that your API credentials are in a file called .cxrc in your home directory. Make sure that such a file exists and has the following contents:

$ # This file should be in your home directory. Replace the
$ # example credentials below with your own.
$ cat .cxrc
authentication john.doe@example.com api&user&12345678asdfghj123456

Replace the email address in the example above with the email address you used as your user name in Audience Analytics, and replace the API key in the example above with the API key associated with your user name.

You can obtain your API key by clicking on your user name in the top right corner of your Piano Insight application.

Usage in different OSs

Verify that the setup works by calling one of the API methods.

Linux and OS X

If you are using Linux or OS X, it's convenient to be able to mix single and double quotes for readability.

$ # Example API call using cx.py. Replace the example
$ # site identifier with one you have read access to.
$ python cx.py /site '{"siteId":"123456789"}'

Replace the site identifier in the example above with one that you have read access to.

Windows

If you are using Windows, use double quotes instead of single quotes around command-line arguments and escape any double quotes within an argument.

> python cx.py /site "{\"siteId\":\"123456789\"}"

Replace the site identifier in the example above with one that you have read access to.

Windows users may also find the cxpy.bat script below handy. This script will handle all Windows-specific parameter issues and call cx.py in the end. With this in your path, you can simply write cxpy instead of python cx.py in the examples above.

@ECHO OFF
FOR /f "tokens=1*" %%a in ("%*") DO (
    SET thepath=%%a
    SET therest=%%b
)
call :strlen therestlength therest
IF %therestlength% == 0 (goto :GETREQUEST) else (goto :POSTREQUEST)

:GETREQUEST
python -m cx %thepath%
goto :END

:POSTREQUEST
SET thequotedrest=%therest:"=\"%
IF /i "%thequotedrest:~0,1%" EQU "'" SET thequotedrest=%thequotedrest:~1,-1%
python -m cx %thepath% "%thequotedrest%"
:END

:strlen <resultVar> <stringVar>
(
    setlocal EnableDelayedExpansion
    set "s=!%~2!#"
    set "len=0"
    for %%P in (4096 2048 1024 512 256 128 64 32 16 8 4 2 1) do (
        if "!s:~%%P,1!" NEQ "" (
            set /a "len+=%%P"
            set "s=!s:~%%P!"
        )
    )
)
(
    endlocal
    set "%~1=%len%"
    exit /b
)

Last updated: June 25, 2026