Overview 

The Audience API provides aggregate demographic information about customer-defined collections of Twitter users.

To build an audience, you first create user segments. There are four ways to build user segments within the Audience API:

  • Upload a custom list of Twitter user IDs
  • Select the followers of any public Twitter account
  • Select a brand’s owned organic audience (impressed and/or engaged users)
  • Select a brand’s owned Tailored Audience

An audience may be comprised of between one and twenty user segments, with a maximum of 30 million users in the audience.

After building an audience, you can query for aggregate insights for one or more supported audience models. All results are displayed as percentages, rounded to the nearest hundredth of a percent (e.g., 7.27).

Note: Twitter’s Audience API employs privacy safeguards (e.g., minimum thresholds, sampling and noise) to protect individual user-level data.


The remainder of this guide describes the API endpoints and how a client can call them using HTTP.

Domain and Access

The Audience API is hosted on data-api.twitter.com and accessible via SSL only (https).

Authentication

The Audience API requires 3-legged authorization for all endpoints. Additionally, Twitter must approve your client application before you can access the API.

Access Control

The Audience API makes use of the access control layer (ACL) for Twitter Ads, called Multi-user login. This ACL allows brands to grant different levels of access to Twitter users that are affiliated with the brand, without turning over the master credentials to the account. By combining multi-user login with 3-legged authorization, users that are affiliated with a brand in Twitter Ads can construct organic audience segments and tailored audience segments as described in the API Reference section. For more information on ads roles and how to set up account permissions, click here.

Data Format 

Request/Response Format

All HTTP requests should be JSON-formatted and UTF-8 encoded. A request should provide an Accept header with value application/json and an Accept-Charset header with value UTF-8.

All HTTP responses will be JSON-formatted and UTF-8 encoded.

Error Response Format

Any HTTP request resulting in 4XX or 5XX response status code will contain one or more error messages in the response body indicating the cause. An example of a response body containing error messages is given below:

{
    "errors": [
        "Some error message",
        "Another error message"
    ]
}

Date/Time Format

All dates and times are represented in Coordinated Universal Time (UTC) in ISO-8601 format.

API Resources 

User Segment

A user segment is a collection of Twitter user IDs and is used as a building block to create audiences. There are four ways to build user segments within the Audience API:

  • Upload a custom list of Twitter user IDs
  • Select the followers of any public Twitter account
  • Select a brand’s owned organic audience (impressed and/or engaged users)
  • Select a brand’s owned Tailored Audience

Any Audience API user may create segments by uploading a list of user IDs, or by selecting the followers of a public Twitter account.

Organic audience segments, however, are available only to the brand that created the content Twitter users were exposed to/engaged with. Similarly, Tailored Audience segments may only be constructed by a brand that created the Tailored Audience in the first place. For more details on Tailored Audiences, click here.

To construct organic or tailored audience segments, an Audience API user must authenticate into the API with the corresponding brand’s credentials, or via an account that has been granted access to the brand’s Twitter Ads account using our Multi-user login framework. For more information on ads roles and how to set up account permissions, click here.

Additional notes:

  • Multiple audiences can be created from the same user segment.
  • Deleting a user segment does not affect created audiences.
  • Twitter user IDs may be appended to a user segment until the segment becomes locked.
  • A user segment is locked after it is used within an audience.
  • A user segment is locked at the time of creation if it is built by selecting either the followers of any public Twitter account, a brand’s owned organic audience, or a brand’s owned Tailored Audience.
  • If segments created via a brand’s owned organic audience do not contain 500 or more users, the Audience API will return an error at the time of segment creation.

Audience

An audience is a collection of user segments which may be queried for aggregate insights using one or more demographic types. An audience may be queried multiple times and the results of each query will reflect the current user demographics. An audience should not need to be queried more than once a day since the user demographics are updated daily. Deleting an audience will not impact the underlying user segments.

Usage

The usage resource contains usage information per customer.

Demographic Types 

The Audience API supports the following user demographic types. Demographic types may be either single valued (user.gender: male or female) or multivalued, meaning that a user may have more than one demographic value associated with his/her profile (user.language: English and/or Chinese).

  • Age → user.age
  • Gender → user.gender
  • Language → user.language
  • Interests → user.interest
  • TV Genre → user.tv.genre (beta)
  • TV Show → user.tv.show (beta)
  • Location: Country → user.location.country
  • Location: Region → user.location.region
  • Location: Metro → user.location.metro
  • Device Category → user.device.os
  • Wireless Device Network → user.device.network

For more information on the composition of each user model, please see the Demographic Definitions section.

Note: Some models are marked “Beta” due to expected future improvements. With that said, we will continue to work on and improve the composition of our models, and whenever possible, will communicate planned changes proactively.



Continue to the API Reference