Treasure Data Audience API Quickstart

Audience API makes it easy to complete tasks within Audience Studio and to automate repetitive marketing activities such as segment creation and campaign activations. Using Audience API, you can analyze the parent segment either as a group or on an individual profile level, and create targeted segments and journeys within that parent segment.

This functionality includes:

  • Create parent segment and/or segments
  • Create funnels and associate specific segments with relevant funnels
  • Create or schedule activations for your segments
  • Create predictive segments and get your customers scored
  • Additional Audience Studio features

By leveraging Audience API endpoints you can create an external application, tool, or CLI to automate common tasks. For example, you may want to integrate Audience API with your continuous deployment service to run tests or set up complex automations.

Setup

Before you can use a Treasure Data REST API, you need two things:

  • An endpoint or baseURL for your API call
  • An API key to authenticate your API call

Determining Endpoints or BaseURLs

Each regional Treasure Data server has specific baseURLs that correspond to it. Here is a list of regional servers and baseURLs for TD APIs.

Getting Your API Keys

You can get your API keys from the My Settings section of the TD Console.

Choosing the Right Type of API Key

There are two types of API keys.

API Key Type Description
master Master API keys can be used to perform all permitted operations that correspond to the user’s permissions in TD Console.
write-only Based on the permissions and access levels associated with a user, write-only API keys only allow importing data into Treasure Data to those databases the user has write access to. This provides an additional layer of security in controlling access to a Treasure Data account through the REST APIs.
Write-only API keys are useful when access has to be provided to 3rd parties or API keys need to be embedded in ingestion libraries (for example, with web page integrations).
warning

Keep your API Master key secure. Master keys grant both read and write access to Treasure Data, and anyone in possession of your Master key could possibly access, corrupt, or delete your data. Do not share your Master keys and be careful not to expose or release your Master key publicly.

Click here to see how to get a write-only API Key.

  1. Login to the Treasure Data Console and go to the API Key page .
  2. If you dont already have a write-only API key, then create one. From the top right, select Actions > Create API Key .
  3. Name the new API Key.
  4. From the Type drop-down menu, select Write-only .
  5. Select Save .
  6. Copy your new Write-Only API Key and use it authenticate the APIs in your project.

Basic Use

Get a list of segments In this case, you want to return a list of segments. This example issues a call to the API to return a list of your segments.

Sample RequestSample Response
Copy
Copied
curl -i -X GET \
  https://api-cdp.treasuredata.com/audiences/:audienceId/segments \
  -H 'Authorization: TD1 YOUR_API_KEY_HERE'
Copy
Copied
[
  {
    "audienceId": 0,
    "id": 0,
    "name": "string",
    "realtime": true,
    "kind": 0,
    "description": "string",
    "segmentFolderId": 0,
    "population": 0,
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "createdBy": {
      "id": "string",
      "name": "string"
    },
    "updatedBy": {
      "id": "string",
      "name": "string"
    },
    "rule": {
      "type": "And",
      "conditions": [
        {}
      ]
    }
  }
]

Create a New Segment

You might want to create many new segments automatically. URI: https://api-cdp.treasuredata.com/audiences/{audienceId}/segments

Sample RequestSample Response
Copy
Copied
curl -i -X POST \
  https://api-cdp.treasuredata.com/audiences/:audienceId/segments \
  -H 'Authorization: TD1 YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "audienceId": 0,
    "name": "string", 
    "kind": 0,
    "funnel_stage": {
      "funnel_id": 0,
      "stage_id": 0
    },
    "description": "string",
    "segmentFolderId": 0,
    "rule": {
      "type": "And",
      "conditions": [
        {}
      ]
    },
    "countPopulation": true
  }'
Copy
Copied
{
  "code": "string",
  "message": "string"
}

Get Query Results

You might want to submit a query to fetch a list of profiles and number of profiles produced by a set of segment rules.

Sample RequestSample Response
Copy
Copied
curl -i -X POST \
  https://api-cdp.treasuredata.com/audiences/:audienceId/segments/queries \
  -H 'Authorization: TD1 YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "columns": [
      "string"
    ],
    "kind": 0,
    "rule": {
      "type": "And",
      "conditions": [
        {}
      ]
    },
    "funnel_stage": {
      "funnel_id": 0,
      "stage_id": 0
    }
  }'
Copy
Copied
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "queryId": "10210520-b895-40ca-bce5-474f9643bf53",
  "status": "success",
  "count": 0,
  "maxPage": 0,
  "error": "string",
  "jobid": "string",
  "countJobid": "string"
}

Create an Activation

You might need to create a new activation (formerly syndication) for your segments.

Sample RequestSample Response
Copy
Copied
curl -i -X POST \
  https://api-cdp.treasuredata.com/audiences/:audienceId/segments/:segmentId/syndications \
  -H 'Authorization: TD1 YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "description": "string",
    "allColumns": true,
    "columns": [
      {
        "column": "campaign",
        "source": {
          "parameters": [
            {
              "string": "c0001",
              "type": "String"
            }
          ],
          "string": "$1"
        }
      }
    ],
    "scheduleType": "daily",
    "scheduleOption": "string",
    "runAt": "string",
    "cron": "string",
    "timezone": "string",
    "connectionId": 0,
    "connectorConfig": {},
    "notifyOn": [
      "onSuccess"
    ],
    "emailRecipients": [
      0
    ]
  }'
Copy
Copied
{
  "code": "string",
  "message": "string"
}

Create a Funnel

You may also want to create a funnel and associate your segments with the funnels you specified.

Sample RequestSample Response
Copy
Copied
curl -i -X POST \
  https://api-cdp.treasuredata.com/audiences/:audienceId/funnels \
  -H 'Authorization: TD1 YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "description": "string",
    "segmentFolderId": 0,
    "stages": [
      {
        "name": "Awareness"
      },
      {
        "id": 1,
        "name": "Interest"
      },
      {
        "name": "Conversion"
      }
    ]
  }'
Copy
Copied
{
  "id": 0,
  "audienceId": 0,
  "segmentFolderId": 0,
  "name": "string",
  "population": 0,
  "description": "string",
  "numSyndications": 0,
  "needToRunWorkflow": true,
  "stages": [
    {
      "id": "1",
      "name": "Awareness",
      "numSyndication": 2,
      "audienceId": "1",
      "funnelId": "10",
      "segmentFolderId": "30",
      "segmentId": "999"
    },
    {
      "id": "2",
      "name": "Interest",
      "numSyndications": 0,
      "audienceId": "1",
      "funnelId": "10",
      "segmentFolderId": "30",
      "segmentId": null
    },
    {
      "id": "3",
      "name": "Conversion",
      "numSyndications": 0,
      "audienceId": "1",
      "funnelId": "10",
      "segmentFolderId": "30",
      "segmentId": null
    }
  ],
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "createdBy": {
    "id": "string",
    "name": "string"
  },
  "updatedBy": {
    "id": "string",
    "name": "string"
  }
}