Piano Insight API | Documentation

Introduction

The Piano Insight platform is a flexible tool that allows you to gain insight in real-time into your site's traffic and how your site's content is being consumed. This page gives an overview of how to use the Piano Insight APIs, as well as a detailed description and examples for each API method. A tutorial covering the API and many of its use cases is found at the API Tutorial.

For JavaScript APIs, see the section on event data.

Using the JSON API documented here assumes that you've already signed up and have a Piano Insight account, so that you can properly authenticate yourself against the API.

Concepts

This documentation makes use of some core concepts throughout. Knowing about these and gaining a bird's-eye view of how the platform works is recommended to be able to work effectively with the platform and with the API.

Title	Description
Platform primer	Provides a bird's-eye view of how the platform works, and what happens when you start using the Cxense Insight platform.
Sites and site groups	Explains what a site is, and how sites can be organized into groups of sites.
Crawling	Explains when and how your site is crawled, and how you can recognize our crawler.
Document parsing	Explains how crawled HTML documents are parsed, and how you can add custom markup.
Content profiles	Explains how content profiles are generated, what they mean, and how they are used by our systems.
User profiles	Explains how user profiles are generated, what they mean, and how they are used by our systems.
Custom taxonomies	Explains how the generation of content profiles and user profiles can be customized.
External data	Explains how non-public data about content and users can be ingested by the platform.
Event data	Explains how events are passed to the platform, e.g., for page view events. Describes both JavaScript APIs and HTTP APIs.
Custom parameters	Explains how you can pass custom event data to the platform, e.g., to provide richer meta data for events.
Metrics	Explains how the most common analytics metrics are defined, and what they measure. Also discusses potential sources for deviations from other systems.
User tracking and privacy	Explains how the platform tracks users, the technologies involved, and how users can opt in and opt out.
Audience estimation	Explains how you can use the Audience Estimation tool.
Short term intents	Describes how you can enable extraction of User Intents.
Long term storage (LTS)	Explains the difference between the standard, full, 31 day Traffic API support and LTS support.
Segment matching	Explains how to define complex audience segments and how segment annotation works.

Usage

Having now familiarized yourself with the basic platform concepts, you'll want to actually start using the API. The API is authenticated and authorized, available over HTTPS, and uses JSON as the data carrier format. Before diving into the individual API methods, you might want to know how the API works in general.

Title	Description
Authentication	Explains how authentication is done, including examples. See also the guide on how to get started.
Requests and responses	Explains how input and output is handled for GET and POST requests, and which generic parameters are available to modify this behavior.
Error codes and responses	Explains how errors are communicated back to the client, and what they mean.

Method overview

Now that you know how the API works in general, this section lists the individual API methods that are available. The API methods are organized in a path-structure that logically groups together related API methods.

Changes to APIs will be backwards compatible, but request and response fields may be added over time as the APIs evolve. API clients must be written to take this into account.

Path	Description
/dmp	Methods for working with DMP statistics.
/dmp/push	Feed new DMP events.
/dmp/title	Retrieve uploaded titles for DMP custom parameters.
/dmp/title/update	Upload human readable titles for custom parameters sent as part of DMP event data.
/dmp/traffic	Retrieve aggregated DMP event data.
/dmp/traffic/event	Retrieve top lists of aggregated DMP event data.
/dmp/traffic/custom	Retrieve top lists of aggregated custom parameters from DMP events.
/dmp/traffic/data	Retrieve DMP events.
/dmp/traffic/user/histogram	Retrieve overall DMP event distribution for users.
/dmp/traffic/user/histogram/event	Retrieve DMP cardinality distribution for users.

/document	Methods for working with documents.
/document/search	Search for documents.
/document/update	Update documents.
/document/delete	Deletes document.
/document/describe	List available fields for /document/search.

/persisted	Methods for working with and executing persisted authenticated requests.
/persisted	Retrieve information about persisted requests.
/persisted/create	Create a new persisted request.
/persisted/update	Update a persisted request.
/persisted/delete	Delete a persisted request.
/persisted/execute	Execute a persisted request.

/processing	Used for manipulating resources that can be used to customize selected aspects of the platform's processing.
/processing/dictionary/read	Retrieve dictionary data and meta data.
/processing/dictionary/create	Create a new dictionary.
/processing/dictionary/delete	Delete a dictionary.
/processing/dictionary/update	Upload new or updated dictionary data or meta data. Dictionaries can be provided as Excel workbooks.
/processing/dictionary/search	Search in a dictionary.
/processing/linguistics/execute	Generates a possibly customized content profile on the fly, given input text.

/profile/content	Methods for working with content profiles.
/profile/content/external/delete	Delete a customer-specified content profile configuration.
/profile/content/external/deleteAll	Delete all customer-specified content profile configurations for a site.
/profile/content/external/read	Retrieve a customer-specified content profile configuration.
/profile/content/external/readAll	Retrieve all customer-specified content profile configurations.
/profile/content/external/update	Update or create a customer-specified content profile configuration. Enables content profile data to be augmented or modified.
/profile/content/fetch	Retrieve the content profile of a given URL.
/profile/content/push	Push a URL for refetching and content processing.
/profile/content/related	Retrieve keywords which are statistically related to a set of specified keywords.

/profile/user	Methods for working with user profiles.
/profile/user	Retrieve a specific user profile.
/profile/user/external/update	Upload information which will be associated with a given user
/profile/user/external/read	Return the annotated data which has been uploaded and associated with a specific user
/profile/user/external/delete	Delete the uploaded information associated with a specified user.
/profile/user/external/link	Read customer user identifiers for an end user.
/profile/user/external/link/list	List all mapped user profiles
/profile/user/external/link/update	Link an end user with a customer-specific user identifier.
/profile/user/segment	Retrieves the list of segments the user has been assigned to.

/public	Unauthenticated methods.
/public/date	Retrieve the current date and time for use with authentication headers.

/reports	Methods for retrieving reports
/reports/search	Report common queries from /document/search for a given site on a given date.
/reports/search/usage	Report number of queries from /document/search for a given site on a given date.

/segment	Methods for working with DMP audience segment definitions.
/segment	Retrieve information about an audience segment.
/segment/create	Create a new audience segment.
/segment/update	Update an existing audience segment.
/segment/delete	Delete an audience segment.
/segment/data/update	Update members for segments with type `external`.
/segment/metadata/read	Read metadata associated with audience segments.

/segment/group	Methods for working with DMP audience segment groups.
/segment/group/read	Retrieve information about existing segment groups.
/segment/group/create	Create a segment group.
/segment/group/update	Update a segment group.
/segment/group/delete	Delete a segment group.

/segment/lookalike	Methods for working with DMP lookalikes
/segment/lookalike	Retrieve information about lookalike configurations.
/segment/lookalike/update	Edit lookalike configuration for an audience segment
/segment/lookalike/quality	Inspect model quality for lookalike segments

/site	Methods for working with sites and site groups.
/site	Retrieve information about sites.
/site/create	Create a new site.
/site/update	Update an existing site.
/site/group	Retrieve information about a site group.
/site/group/create	Create a new site group.
/site/group/update	Update an existing site group.

/traffic	Methods for working with traffic statistics.
/traffic	Retrieve aggregated traffic data.
/traffic/event	Retrieve top lists of aggregated event data.
/traffic/event/describe	List groups available in /traffic/event.
/traffic/keyword	Retrieve top lists of aggregated keywords from events and content profiles.
/traffic/keyword/describe	List groups available in /traffic/keyword.
/traffic/custom	Retrieve top lists of aggregated custom parameters from events.
/traffic/custom/describe	List groups available in /traffic/custom.
/traffic/compare	Compare the aggregated traffic based on two different sets of filters.
/traffic/related	Retrieve similar items based on the recent page views.
/traffic/user	Retrieve top lists of users behind the events matching a filter.
/traffic/user/interest	Retrieve top lists of aggregated user interests.
/traffic/user/keyword	Retrieve top lists for a range of aggregated user data.
/traffic/user/external	Retrieve top lists for user data which has been associated with users through /profile/user/external/update.
/traffic/user/histogram	Retrieve overall traffic distribution for users.
/traffic/user/histogram/event	Retrieve cardinality distribution for users.
/traffic/data	Retrieve events.

Scenarios

Application scenarios frequently involve combining multiple API methods and platform capabilities to achieve a particular goal. This section provides pointers and examples on how to best address a few such common scenarios.

Task	Description
Working with Excel	Describes how to interface with the API if you're using Microsoft Excel.
Manual tuning of content profiles	Describes how you can tweak or override content profile elements.
Retrieving user data	Describes how to retrieve user data for display or export purposes.

Last updated: June 25, 2026