Skip to main content

Treasure Data

Treasure Data is a customer data platform (CDP) and cloud data warehouse built on a managed Presto/Hive query engine. The TD API v3 exposes management of databases, tables, and query jobs, along with bulk import and bulk load (connector) session tracking, while a separate high-throughput ingestion endpoint accepts streaming JSON record writes.

Treasure Data icon

Power end-to-end data operations for your Treasure Data API with Nexla. Our bi-directional Treasure Data connector is purpose-built for Treasure Data, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Treasure Data or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Treasure Data workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

  • Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
  • Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
  • API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
  • Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites​

Treasure Data authenticates REST API requests with an API key sent in the Authorization header using the TD1 scheme (for example, Authorization: TD1 your-api-key). Every TD account is created with a Master API key and a Write-only API key by default, and both can be found in the same place in the TD Console.

To obtain your Treasure Data API key, follow these steps:

  1. Sign in to the Treasure Data Console.

  2. Navigate to My Settings > API Keys.

  3. To use your account's existing key, copy the Master API Key or Write-only API Key shown on this page. To create a new key, select Actions > Create API Key, give it a name, choose a Type (Master or Write-only), and select Save.

  4. Note which region your TD account lives in (US, Europe, Korea, or Japan) — this determines the API base URL and ingestion base URL you'll select when creating the Nexla credential.

Treasure Data issues two kinds of API keys with different scopes:

  • Master API Key — grants full read and write access to your account, including database/table management, job submission, and record ingestion. Required for any data source (read) pipeline.
  • Write-only API Key — can only be used to import data into databases it has been granted write access to. It cannot list databases/tables, submit queries, or read job status. Use this key type for ingestion-only (destination) pipelines where you want to limit the blast radius of a leaked credential.

Master API keys grant full read/write access to your Treasure Data account and should be treated as highly sensitive — anyone holding one can read, modify, or delete your data. Prefer a Write-only API key for destination-only pipelines. If a key is compromised, revoke it and generate a new one from My Settings > API Keys in the TD Console.

For more information about API keys and authentication, see the Treasure Data "Getting Your API Keys" documentation and the TD API reference.

Authenticate​

Credentials required​

Authenticate using a Master API key. Grants full read and write access. Use for source + sink pipelines.

FieldRequiredSecretDescription
Master API KeyYesYesYour Treasure Data Master API Key. Found in TD Console → Profile → API Keys. Full read/write access.
TD API Base URLYesNoManagement API base URL for your Treasure Data region. Allowed values: US (us01) — Default; Europe (eu01); Korea (ap02); Japan (ap01 / co.jp)
Ingestion API Base URLYesNoRecord ingestion base URL for your Treasure Data region. Used by the Ingest Records sink endpoint. Allowed values: US (us01) — Default; Europe (eu01); Korea (ap02); Japan (ap01)

Create a credential in Nexla​

  1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

  2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

  3. Select the credential type that matches how this credential will be used:

    • Treasure Data Master API Key — enter your key in the Master API Key field. This is the key you obtained in Prerequisites from My Settings > API Keys in the TD Console. Required for data source pipelines (listing databases/tables, submitting queries, checking job status).

    • Treasure Data Write-Only API Key — enter your key in the Write-Only API Key field. Use this credential type only for destination (ingestion) pipelines, since a Write-only key cannot read databases, tables, or jobs.

  4. For either credential type, select the TD API Base URL and Ingestion API Base URL values that match your Treasure Data account's region (US, Europe, Korea, or Japan). Using the wrong region will cause authentication or connectivity errors even with a valid key.

    Both the Master and Write-only API key values are sensitive and should be treated as secrets. If a key is compromised, revoke it and generate a new one from My Settings > API Keys in the TD Console.

    For detailed information about API keys, regions, and available endpoints, see the Treasure Data "Getting Your API Keys" documentation and the TD API reference.

  5. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.

Use as a data source​

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Treasure Data connector tile, then select the credential that will be used to connect to your Treasure Data account, and click Next; or, create a new Treasure Data credential for use in this flow. Use a Treasure Data Master API Key credential for all of the endpoint templates below, since a Write-only key cannot read databases, tables, jobs, or query results.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Treasure Data endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below.

List Databases

Retrieve all databases in the authenticated Treasure Data account.

  • No additional configuration parameters are required for this endpoint.

For details on request parameters and response fields, see the Treasure Data API documentation.

List Tables

Retrieve all tables within a specified Treasure Data database.

  • Database Name (required) — The name of the Treasure Data database to list tables from.

For details on request parameters and response fields, see the Treasure Data API documentation.

List Jobs

Retrieve the job history for the account. Supports filtering by status. Paginated using from/to index bounds.

  • Status Filter — Filter jobs by status. Leave blank to retrieve all statuses. Accepted values: (blank), success, running, error, queued, killed.

For details on request parameters and response fields, see the Treasure Data API documentation.

Execute Query

Submit a SQL query (Presto or Hive), poll until completion, and retrieve results. This is a three-step async workflow: issue the job, poll its status until it succeeds, then fetch the results.

  • Database Name (required) — The Treasure Data database to run the query against.
  • SQL Query (required) — The SQL query to execute. Use standard Presto or Hive SQL syntax depending on the selected engine.
  • Query Engine — The query engine to use. Accepted values: presto (recommended, default), hive. Presto is recommended for interactive queries; Hive for large batch workloads.
  • Job Priority — Job scheduling priority. Higher values run sooner. Accepted values: -2 (lowest) through 2 (highest). Default: 0 (normal).

Because this endpoint polls until the job reaches a success status, query duration directly affects how long the source takes to return data. For details on query jobs, engines, and the async job lifecycle, see the Treasure Data API documentation.

List Bulk Imports

Retrieve all bulk import sessions in the account, including their status, record counts, and associated database/table.

  • No additional configuration parameters are required for this endpoint.

For details on request parameters and response fields, see the Treasure Data Bulk Import API documentation.

List Bulk Loads (Connectors)

Retrieve all bulk load connector sessions configured in the account, including schedule, source config, and target database/table.

  • No additional configuration parameters are required for this endpoint.

For details on request parameters and response fields, see the Treasure Data Bulk Loads API documentation.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration​

Treasure Data data sources can also be manually configured to ingest data from any valid TD API v3 endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

All TD API v3 requests are authenticated with the Authorization: TD1 <api-key> header and are issued against the region-specific base URL configured on the credential (for example, https://api.treasuredata.com for the US region).

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Treasure Data data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination​

Click the + icon on the Nexset that will be sent to the Treasure Data destination, and select the Send to Destination option from the menu. Select the Treasure Data connector from the list of available destination connectors, then select the credential that will be used to connect to your Treasure Data account, and click Next; or, create a new Treasure Data credential for use in this flow. A Treasure Data Write-Only API Key credential is sufficient for ingestion and is recommended to limit the scope of the credential.

Endpoint templates​

Nexla provides a pre-built template that can be used to rapidly configure a destination to write records into a Treasure Data table. Select the endpoint to which data will be sent from the Endpoint pulldown menu, then click on the template below to expand it, and follow the instructions to configure additional endpoint settings.

Ingest Records

Write records to a Treasure Data table via the bulk JSON ingestion API. Records are batched and wrapped in a records envelope before being sent. If the table does not already exist, it is created automatically, and any new columns encountered are added to the schema on first write.

  • Target Database (required) — The Treasure Data database to write records into.
  • Target Table (required) — The Treasure Data table to write records into. Created automatically if it doesn't exist.

If your records include a time field, it must be a Unix timestamp expressed in UTC seconds (not milliseconds); records without a time field are timestamped with their ingestion time. Records are sent in batches of up to 500 to the ingestion API base URL configured on the credential (for example, https://us01.records.in.treasuredata.com for the US region). For details on the bulk ingestion request format, see the Treasure Data API documentation.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to send a test payload and verify that the destination is configured correctly before saving.

Manual configuration​

Treasure Data destinations can also be manually configured to send data to any valid TD ingestion or API v3 endpoint. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.

The bulk ingestion endpoint expects a Content-Type: application/vnd.treasuredata.v1.bulk+json request with records wrapped in a records array, and is authenticated with the same Authorization: TD1 <api-key> header used for the management API.

Save & activate​

Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured Treasure Data endpoint, open the destination resource menu, and select Activate.

The Nexset data will not be sent to the Treasure Data endpoint until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.