Audiences
Tailored Audiences¶
GET accounts/:account_id/tailored_audiences¶
Retrieve details for some or all Tailored Audiences associated with the current account.
Resource URL¶
https://ads-api.twitter.com/4/accounts/:account_id/tailored_audiences
Parameters¶
Name | Description |
---|---|
account_id
required
|
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: |
count
optional
|
Specifies the number of records to try and retrieve per distinct request. Type: int Default:
200 Min, Max:
1 , 1000 |
cursor
optional
|
Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: |
permission_scope
optional
|
Allows filtering the response to lists you own or lists that have been shared with you. By default, without specifying this parameter you will only see audiences you own. Type: enum Default:
OWNER Possible values:
OWNER , SHARED |
sort_by
optional
|
Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: |
tailored_audience_ids
optional
|
Scope the response to just the desired tailored audiences by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: |
with_deleted
optional
|
Include deleted results in your request. Type: boolean Default:
false Possible values:
true , false |
with_total_count
optional
|
Include the Note: This parameter will be ignored if Note: Requests which include Type: boolean Default:
false Possible values:
true , false |
Example Request¶
GET https://ads-api.twitter.com/4/accounts/18ce54d4x5t/tailored_audiences?tailored_audience_ids=1nmth
Example Response¶
{
"request": {
"params": {
"tailored_audience_ids": [
"1nmth"
],
"account_id": "18ce54d4x5t"
}
},
"next_cursor": null,
"data": [
{
"targetable": true,
"name": "twurl-using-subshell-for-file",
"targetable_types": [
"CRM",
"EXCLUDED_CRM"
],
"audience_type": "CRM",
"permission_level": "READ_WRITE",
"is_owner": true,
"id": "1nmth",
"reasons_not_targetable": [],
"created_at": "2017-01-08T08:19:58Z",
"updated_at": "2017-01-08T16:21:13Z",
"partner_source": "OTHER",
"deleted": false,
"audience_size": 1470
}
]
}
GET accounts/:account_id/tailored_audiences/:tailored_audience_id¶
Retrieve specific Tailored Audiences associated with the current account.
Resource URL¶
https://ads-api.twitter.com/4/accounts/:account_id/tailored_audiences/:tailored_audience_id
Parameters¶
Name | Description |
---|---|
account_id
required
|
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: |
tailored_audience_id
required
|
A reference to the tailored audience you are operating with in the request. Type: string Example: |
with_deleted
optional
|
Include deleted results in your request. Type: boolean Default:
false Possible values:
true , false |
Example Request¶
GET https://ads-api.twitter.com/4/accounts/18ce54d4x5t/tailored_audiences/2906h
Example Response¶
{
"request": {
"params": {
"tailored_audience_id": "2906h",
"account_id": "18ce54d4x5t"
}
},
"data": {
"targetable": false,
"name": "developers",
"targetable_types": [
"CRM",
"EXCLUDED_CRM"
],
"audience_type": "CRM",
"permission_level": "READ_WRITE",
"is_owner": true,
"id": "2906h",
"reasons_not_targetable": [],
"created_at": "2017-08-22T23:34:26Z",
"updated_at": "2017-08-22T23:34:26Z",
"partner_source": "OTHER",
"deleted": false,
"audience_size": 140321
}
}
POST accounts/:account_id/tailored_audiences¶
Create a new placeholder Tailored Audience associated with the current account.
Use the POST accounts/:account_id/tailored_audience_changes endpoint to add, remove, or replace audience members based on an uploaded audience file.
Resource URL¶
https://ads-api.twitter.com/4/accounts/:account_id/tailored_audiences
Parameters¶
Name | Description |
---|---|
account_id
required
|
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: |
name
required
|
The display name for this audience. Type: string Example: |
Example Request¶
POST https://ads-api.twitter.com/4/accounts/18ce54d4x5t/tailored_audiences?name=developers
Example Response¶
{
"data": {
"targetable": false,
"name": "developers",
"targetable_types": [
"CRM",
"EXCLUDED_CRM"
],
"audience_type": "CRM",
"permission_level": "READ_WRITE",
"is_owner": true,
"id": "2906h",
"reasons_not_targetable": [
"PROCESSING",
"TOO_SMALL"
],
"created_at": "2017-08-22T23:34:26Z",
"updated_at": "2017-08-22T23:34:26Z",
"partner_source": "OTHER",
"deleted": false,
"audience_size": null
},
"request": {
"params": {
"account_id": "18ce54d4x5t",
"name": "developers"
}
}
}
POST batch/accounts/:account_id/tailored_audiences¶
Allows for batch creation of Tailored Audiences. See the Tailored Audiences Overview page for information on audiences.
Note: This batch endpoint is currently in closed beta and available to select advertisers. During this beta period, only Flexible Audiences based on mobile tailored audiences can be created.
Batch Requests
- The current maximum batch size is 10.
- All parameters are sent in the request body and a
Content-Type
ofapplication/json
is required. - Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.
Batch Responses
Batch API responses return an ordered collection of items. Otherwise, they are identical in structure to their corresponding single-item endpoints.
Batch Errors
- Request-level errors (eg. max batch size exceeded) are shown in the response
under the
errors
object. - Item-level errors (eg. missing required parameter) are shown in the response
under the
operation_errors
object.
Flexible Audiences¶
- Flexible Audiences are immutable once created.
- Tailored Audiences are passed in a tree structure with boolean logic combinations to create Flexible Audiences
- A maximum of 10 Tailored Audiences leaf nodes can be used to create a Flexible Audience.
https://ads-api.twitter.com/4/batch/accounts/:account_id/tailored_audiences
Name | Description |
---|---|
account_id
required
|
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: |
audience_type
required
|
The type of audience to create. Type: enum Possible values: |
child_segments
required
|
An array containing objects which define the subset of a Tailored Audience’s
members that you would like to target. Each object should contain a
Type: array |
name
required
|
The display name for the audience. Type: string Example: |
operation_type
required
|
The per item operation type being performed. Type: enum Possible values: |
params
required
|
A JSON object containing all params for the Campaign object. Type: string Example: |
boolean_operator
sometimes required
|
The logical relationship between the child segments in its parent (containing) object. Required if child_segments is non-empty for the parent object. Type: enum Possible values: |
lookback_window
sometimes required
|
An integer value specifying the range of days within which the user has taken the specific action and qualified for the given tailored audience. Type: int Possible values: |
segments
sometimes required
|
An object containing a Type: object |
tailored_audience_id
sometimes required
|
The id of the tailored audience to use as a child segment. Type: string Example: |
frequency
optional
|
An integer value specifying the frequency within the lookback window that the user has taken the specific action and qualified for the given tailored audience. Type: int Default value: |
frequency_comparator
optional
|
The comparator to the Note: In the values below, Type: string Possible values: |
negate
optional
|
Negates the segment and thus is excluded in the combination. Type: boolean Default value:
true Possible values:
true , false |
POST https://ads-api.twitter.com/4/batch/accounts/18ce54d4x5t/tailored_audiences
[
{
"operation_type":"Create",
"params":{
"name":"my_flexible_audience_name",
"audience_type":"FLEXIBLE",
"segments":{
"boolean_operator":"AND",
"child_segments":[
{
"tailored_audience_id":"TYIF",
"frequency":1,
"frequency_comparator":"NUM_GT",
"lookback_window":30,
"negate":true,
"child_segments":[
]
},
{
"boolean_operator":"OR",
"child_segments":[
{
"tailored_audience_id":"TXR1",
"lookback_window":30,
"child_segments":[
]
},
{
"tailored_audience_id":"TYFO",
"frequency":1,
"frequency_comparator":"NUM_GT",
"lookback_window":30,
"negate":true,
"child_segments":[
]
}
]
}
]
}
}
}
]
{
"data": {
"targetable": false,
"name": "my_flexible_audience_name",
"targetable_types": [
"FLEXIBLE",
"EXCLUDED_FLEXIBLE"
],
"audience_type": "FLEXIBLE",
"id": "13ld7",
"reasons_not_targetable": [
"PROCESSING",
"TOO_SMALL"
],
"metadata": [
{
"tailored_audience_id": "13ld7",
"account_id": "qsx3w2",
"name": "my_flexible_audience_name",
"audience_source": "FLEXIBLE_AUDIENCE",
"upload_status": "UPLOADED",
"segments": {
"boolean_operator": "AND",
"frequency": 1,
"frequency_comparator": "NUM_GTE",
"negate": false,
"child_segments": [
{
"tailored_audience_id": "tyif",
"lookback_window": 30,
"frequency": 1,
"frequency_comparator": "NUM_GT",
"negate": true,
"child_segments": [
]
},
{
"boolean_operator": "OR",
"frequency": 1,
"frequency_comparator": "NUM_GTE",
"negate": false,
"child_segments": [
{
"tailored_audience_id": "txr1",
"lookback_window": 30,
"frequency": 1,
"frequency_comparator": "NUM_GTE",
"negate": false,
"child_segments": [
]
},
{
"tailored_audience_id": "tyfo",
"lookback_window": 30,
"frequency": 1,
"frequency_comparator": "NUM_GT",
"negate": true,
"child_segments": [
]
}
]
}
]
}
}
],
"created_at": "2015-11-10T21:26:43Z",
"updated_at": "2015-11-11T01:11:47Z",
"partner_source": "OTHER",
"deleted": false,
"audience_size": null
},
"request": [
{
"params": {
"name": "my_flexible_audience_name",
"audience_type": "FLEXIBLE",
"segments": {
"boolean_operator": "AND",
"child_segments": [
{
"tailored_audience_id": "TYIF",
"lookback_window": 30,
"frequency": 1,
"frequency_comparator": "NUM_GT",
"negate": true,
"child_segments": [
]
},
{
"boolean_operator": "OR",
"child_segments": [
{
"tailored_audience_id": "TXR1",
"lookback_window": 30,
"child_segments": [
]
},
{
"tailored_audience_id": "TYFO",
"lookback_window": 30,
"frequency": 1,
"frequency_comparator": "NUM_GT",
"negate": true,
"child_segments": [
]
}
]
}
]
},
"account_id": "qsx3w2"
},
"operation_type": "Create"
}
]
}
DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id¶
Delete the specified Tailored Audience belonging to the current account.
Resource URL¶
https://ads-api.twitter.com/4/accounts/:account_id/tailored_audiences/:tailored_audience_id
Parameters¶
Name | Description |
---|---|
account_id
required
|
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: |
tailored_audience_id
required
|
A reference to the tailored audience you are operating with in the request. Type: string Example: |
Example Request¶
DELETE https://ads-api.twitter.com/4/accounts/18ce54d4x5t/tailored_audiences/2906h
Example Response¶
{
"data": {
"targetable": false,
"name": "developers",
"targetable_types": [
"CRM",
"EXCLUDED_CRM"
],
"audience_type": "CRM",
"permission_level": "READ_WRITE",
"is_owner": true,
"id": "2906h",
"reasons_not_targetable": [
"TOO_SMALL"
],
"created_at": "2017-08-22T23:34:26Z",
"updated_at": "2017-08-30T18:09:00Z",
"partner_source": "OTHER",
"deleted": true,
"audience_size": null
},
"request": {
"params": {
"tailored_audience_id": "2906h",
"account_id": "18ce54d4x5t"
}
}
}