Retrieve the namespaces of tags that have been applied to interactions stored in an index.

To learn how to use the endpoints together take a look at our PYLON API step-by-step page.

An HTTPS GET request sent to:

A successful call to this endpoint returns: 200 OK and a JSON object.


Parameter Description

The id of the recording you want to retrieve tag namespaces for.

Example values: d1b7d73b47c639ea3cc290595bca888ca4388afe


Sample request

curl -X GET 
  -H 'Authorization: username:api_key'


Tags in the tag tree are grouped by namespaces you specify in your tagging rules. This endpoint returns a list of tag namespaces that exist for interactions in the specified index.

It is important to note that redaction limits are also applied to the results of requests to this endpoint. The platform will return a list of tag namespaces only when there are at least 1,000 unique authors represented in your index.

Tag namespaces are only returned where, across the tags in the namespace, at least 100 unique authors are represented.

So for example, if you have 10,000 unique authors represented in your index and tags representing the following counts of unique authors:

Tag namespace Tag Unique Authors
animals.sea 110
lobster 60
shark 70 1150
gorilla 900
giraffe 200
animals.air 90
eagle 70
falcon 30

Note that the count of unique authors for a namespace is not necessarily equal to the sum of the unique author counts of its child tags. This is because some authors may appear in both tags.

The animals.sea and namespaces will be returned, but the animals.air namespace will not.

The response from the endpoint will be:

HTTP/1.1 200 OK

["interaction.tag_tree.animals.sea", ""]

Note that if you have updated your filter over time to add or remove tag rules, tag namespaces will be returned that exist for interactions in your index as long as they meet the above rules, regardless of whether the tags still exist in your current interaction filter CSDL.


Response code Description
200 OK DataSift returns a JSON array of strings, with each string representing a tag namespace.
404 Not Found Could not find a recording with the supplied id.


  1. All calls to the API must be properly authenticated with a DataSift username and API key.
  2. All calls to the API must be versioned. The current version is v1.3.
  3. Take a look at our Changelog page to review the changes we've made to the DataSift API over time.

Revision history


Up to v1.2 this endpoint required the hash of the CSDL interaction filter you wanted to retrive tags for.

From v1.3 it takes the id of the recording you want to retrive tags for. The id is supplied in the JSON returned by your call to the /pylon/start endpoint.

Resource information

Rate limit cost: 25

Requires authentication: Yes

Response formats: JSON, JSONP