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/8/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 |
q optional |
An optional query to scope resource by Note: This performs case-insensitive prefix matching. Type: string Min, Max length: 1 , 255 |
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 and Note: Requests which include Type: boolean Default: false Possible values: true , false |
Example Request¶
GET https://ads-api.twitter.com/8/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",
"owner_account_id": "18ce54d4x5t",
"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/8/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/8/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",
"owner_account_id": "18ce54d4x5t",
"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.
Resource URL¶
https://ads-api.twitter.com/8/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/8/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",
"owner_account_id": "18ce54d4x5t",
"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"
}
}
}
PUT accounts/:account_id/tailored_audiences/:tailored_audience_id¶
Update the specfic Tailored Audience associated with the current account.
Resource URL¶
https://ads-api.twitter.com/8/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: |
name optional |
The display name for this audience. Type: string Example: |
Example Request¶
PUT https://ads-api.twitter.com/8/accounts/18ce54d4x5t/tailored_audiences/2906h?name=developers_changed
Example Response¶
{
"data": {
"targetable": false,
"name": "developers_changed",
"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_changed"
}
}
}
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.
Resource URL¶
https://ads-api.twitter.com/8/batch/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: |
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: |
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 |
Example Request¶
POST https://ads-api.twitter.com/8/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":[
]
}
]
}
]
}
}
}
]
Example Response¶
{
"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/8/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/8/accounts/18ce54d4x5t/tailored_audiences/2906h
Example Response¶
{
"data": {
"targetable": false,
"name": "developers",
"targetable_types": [
"CRM",
"EXCLUDED_CRM"
],
"audience_type": "CRM",
"permission_level": "READ_WRITE",
"owner_account_id": "18ce54d4x5t",
"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"
}
}
}