Twitter Custom Audience Export Integration

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

You can write job results directly to your Twitter Custom Audience.

Twitter Custom Audiences allow you to leverage your off-platform customer information enabling you to create unique audience segments used for targeting, exclusion, and lookalike expansion.

Prerequisites

• Basic knowledge of Treasure Data, including the TD Toolbelt
• A Twitter Ads Account or an account with Ads Manager role
• Authorized Treasure Data Twitter app access to your Twitter Ads Account

Use the TD Console

Create a New Connection

1. From TD Console, navigate to the catalog in the Integrations Hub. Search for and select Twitter Custom Audience.

2. Select Create Authentication. The following dialog opens.

3. Select an existing OAuth connection for Twitter, or select the link under OAuth connection to create a new one.

Create a New OAuth Connection

1. Log into your Twitter account in the browser (if you haven’t logged in previously) and grant access:

Or grant access to the Treasure Data app when you are already logged in.

2. After you're redirected back to Treasure Data Connections, repeat the first step (Create a new connection) and choose your new OAuth connection.

3. Name your newly created connection and save it for later use.

4. Configure Output Results The Output result needs to follow the Twitter Custom List data specifications here. We support single column, single type.

• TWITTER_ID: Twitter user IDs
• DEVICE_ID: IDFA, AdID or Android ID of Twitter users
• EMAIL: Email addresses
• TWITTER_HANDLE: Twitter users name aka. Screen names

5. Check Output results at the top of your query editor and select your Twitter Custom Audience connection as follows:

6. Edit the following parameters:

• Twitter Ad Account ID (required, api param: ad_account_id): This is your Twitter Ad Account ID. See Appendix C for getting account id.

• Custom Audience Name (required, api param: audience_name): Name of Custom Audience list to create.

  • Important note: If you have many Tailored Audience lists with similar names as this input, the latest Custom Audience Name will be used. We recommend that you give your Custom Audience list a unique name.
  • Important note: You cannot use audience names that are associated with deleted audiences. When creating a new audience, you will receive an error message if you attempt to reuse a name that is associated with a deleted audience.

• Audience type (require, api param: audience_type): Type of entry in the list. It is one of email, id, device id, or handle.

• No need to normalize and hash records (default false, api param: pre_hashed): Indicates whether the data has already been normalized and hashed. If not, TD automatically normalizes and hashes the records.

• Expires at (api param: expires_at)**:**The UTC time format as "yyyy-MM-ddTHH:mm:ssZ" (i.e., 2025-10-28T10:30:00Z) at which the custom audience association(s) should expire. If it's empty, default value will be 13 months from the request timestamp.

• Skip on invalid records (default false): Indicates whether invalid records should be ignored.

• Mode (Default Update, api param: mode):Operation type being performed

  • Update: Add new users to the destination Audience
  • Delete: Delete users with identifiers that are exported by this feature from the destination Audience

• Retry limit (optional, default 6): Number of retries before it gives up.

• Initial intervals in milliseconds between retries (optional, default 10000): Interval to retry if a recoverable error happens (in millisecond).

• Maximum intervals in milliseconds between retries (optional, default to 32000) : Maximum time in milliseconds between retrying attempts.

  Sample Configuration

Write the Query to Populate a Custom Audience List

1. Treasure Data supports the creation of a new Custom Audience list. On the Treasure Data console, run the following query with Output results into a connection of Twitter Custom Audience (see Appendix A for more details of column naming):

SELECT email FROM (
  VALUES ('demo1@example.com'),
         ('demo2@example.com'),
         ('demo3@example.com')
)  tbl (email)

The preceding query will not match any real users as it is for demo purposes only. Further, it requires no source table (for the ease of testing out this feature), but you still need to choose your database, so pick “sample_datasets” or any other arbitrary table. The query completes in a few seconds.

2. Check the Twitter Audience Manager for your new list.

Twitter takes up to 24 hours to validate your newly created list. Therefore, the list will show the status as “Processing”.

You can see the status change to “Ready” (or an error if the list is not valid) within the next 6 to 8 hours.

(Optional) Schedule Query Export Jobs

You can use Scheduled Jobs with Result Export to periodically write the output result to a target destination that you specify.

Treasure Data's scheduler feature supports periodic query execution to achieve high availability.

When two specifications provide conflicting schedule specifications, the specification requesting to execute more often is followed while the other schedule specification is ignored.

For example, if the cron schedule is '0 0 1 * 1', then the 'day of month' specification and 'day of week' are discordant because the former specification requires it to run every first day of each month at midnight (00:00), while the latter specification requires it to run every Monday at midnight (00:00). The latter specification is followed.

Scheduling your Job Using TD Console

1. Navigate to Data Workbench > Queries

2. Create a new query or select an existing query.

3. Next to Schedule, select None.

4. In the drop-down, select one of the following schedule options:

   Drop-down Value	Description
   Custom cron...	Review Custom cron... details.
   @daily (midnight)	Run once a day at midnight (00:00 am) in the specified time zone.
   @hourly (:00)	Run every hour at 00 minutes.
   None	No schedule.

Custom cron... Details

 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)

The following named entries can be used:

• Day of Week: sun, mon, tue, wed, thu, fri, sat.
• Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec.

A single space is required between each field. The values for each field can be composed of:

1. (Optional) You can delay the start time of a query by enabling the Delay execution.

Execute the Query

Save the query with a name and run, or just run the query. Upon successful completion of the query, the query result is automatically exported to the specified destination.

(Optional) You can delay the start time of a query by enabling the Delay execution.

Activate a Segment in Audience Studio

You can also send segment data to the target platform by creating an activation in the Audience Studio.

1. Navigate to Audience Studio.
2. Select a parent segment.
3. Open the target segment, right-mouse click, and then select Create Activation.
4. In the Details panel, enter an Activation name and configure the activation according to the previous section on Configuration Parameters.
5. Customize the activation output in the Output Mapping panel.

• Attribute Columns
  • Select Export All Columns to export all columns without making any changes.
  • Select + Add Columns to add specific columns for the export. The Output Column Name pre-populates with the same Source column name. You can update the Output Column Name. Continue to select + Add Columnsto add new columns for your activation output.
• String Builder
  • + Add string to create strings for export. Select from the following values:
    • String: Choose any value; use text to create a custom value.
    • Timestamp: The date and time of the export.
    • Segment Id: The segment ID number.
    • Segment Name: The segment name.
    • Audience Id: The parent segment number.

6. Set a Schedule.

• Select the values to define your schedule and optionally include email notifications.

7. Select Create.

Appendix

Custom Audience Data

The Output result needs to follow the Twitter Custom List data specifications here. We support single column, single type.

• TWITTER_ID: Twitter user IDs
• DEVICE_ID: IDFA, AdID or Android ID of Twitter users
• EMAIL: Email addresses
• TWITTER_HANDLE: Twitter users name aka. Screen names

Data Normalization and Hashing

Our result output can normalize your values automatically to follow Twitter’s normalizing rules. See here.

All values, uploaded to Twitter for matching, need to be normalized with the normalizing rules of Twitter. The values will narrowly miss chances to match if they are not normalized. If you need to normalize values by yourselves, apply your own normalization before submitting the output.

The conversion below is actually applied per type in our result output for normalization.

• Email Addresses: Lowercase, remove leading and trailing spaces; ex: support@twitter.com
• Twitter User Name: No @, lowercased and leading and trailing spaces trimmed; ex: jack
• Twitter User IDs: Standard integer; ex: 143567
• Device IDs: Lower-cased with dashes (IDFA), original format on device, not capitalized with dashes (AdID) and original format on device, not capitalized without dashes or spaces (Android ID); ex: 4b61639e-47cc-4056-a16a-c8217e02946 and af3802a465767e36

After normalization, the data must be hashed using SHA256**, without a salt**.  Additionally, the final output hash must be in lower case.
For example, 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d and not49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D

Twitter Ads Account Information

Access to an Ads Account is the pre-requisite to create the Custom Audience List. The account ID can be retrieved from the Account Settings Page