Campaign Management
Campaigns¶
GET accounts/:account_id/campaigns¶
Retrieve details for some or all campaigns associated with the current account.
Resource URL¶
https://ads-api.twitter.com/4/accounts/:account_id/campaigns
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: |
campaign_ids
optional
|
Scope the response to just the desired campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. 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: |
draft_only
optional
|
Scope the response to just draft campaigns. Type: boolean Default:
false Possible values:
true , false |
funding_instrument_ids
optional
|
Scope the response to just the campaigns under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: |
sort_by
optional
|
Sorts by supported attribute in ascending or descending order. See Sorting for more information. 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/campaigns?campaign_ids=8wku2
Example Response¶
{
"request": {
"params": {
"campaign_ids": [
"8wku2"
],
"account_id": "18ce54d4x5t"
}
},
"next_cursor": null,
"data": [
{
"name": "batch campaigns",
"start_time": "2017-06-30T00:00:00Z",
"reasons_not_servable": [
"PAUSED_BY_ADVERTISER",
"INCOMPLETE"
],
"servable": false,
"daily_budget_amount_local_micro": 140000000,
"end_time": null,
"funding_instrument_id": "lygyi",
"duration_in_days": null,
"standard_delivery": true,
"total_budget_amount_local_micro": null,
"id": "8wku2",
"entity_status": "PAUSED",
"account_id": "18ce54d4x5t",
"frequency_cap": null,
"currency": "USD",
"created_at": "2017-06-30T21:17:16Z",
"updated_at": "2017-06-30T21:17:16Z",
"deleted": false
}
]
}
GET accounts/:account_id/campaigns/:campaign_id¶
Retrieve a specific campaign associated with the current account.
Resource URL¶
https://ads-api.twitter.com/4/accounts/:account_id/campaigns/:campaign_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: |
campaign_id
required
|
A reference to the campaign 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/campaigns/8wku2
Example Response¶
{
"request": {
"params": {
"campaign_id": "8wku2",
"account_id": "18ce54d4x5t"
}
},
"data": {
"name": "batch campaigns",
"start_time": "2017-06-30T00:00:00Z",
"reasons_not_servable": [
"PAUSED_BY_ADVERTISER",
"INCOMPLETE"
],
"servable": false,
"daily_budget_amount_local_micro": null,
"end_time": null,
"funding_instrument_id": "lygyi",
"duration_in_days": null,
"standard_delivery": true,
"total_budget_amount_local_micro": null,
"id": "8wku2",
"entity_status": "PAUSED",
"account_id": "18ce54d4x5t",
"frequency_cap": null,
"currency": "USD",
"created_at": "2017-06-30T21:17:16Z",
"updated_at": "2017-06-30T21:17:16Z",
"deleted": false
}
}
POST accounts/:account_id/campaigns¶
Create a new campaign associated with the current account.
Note: There is a default limit of 200 active campaigns per account. However, there is no limit to the number of inactive campaigns. This limit can be raised to 8,000 active campaigns. To enable the higher limit, the advertiser must make the request to their Twitter Account Manager.
Resource URL¶
https://ads-api.twitter.com/4/accounts/:account_id/campaigns
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: |
funding_instrument_id
required
|
The identifier for the funding instrument to create the campaign under. Type: string Example: |
name
required
|
The name for the campaign. Type: string Example: |
start_time
required
|
The time, expressed in ISO 8601, that the campaign will begin. Type: string Example: |
daily_budget_amount_local_micro
optional
|
The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time. Note: This should be less than or equal to the
Type: long Example: |
duration_in_days
optional
|
The time period within which the Type: int Possible values: |
end_time
optional
|
The time, expressed in ISO 8601, that the campaign will end. Type: string Example: |
entity_status
optional
|
The campaign status. Type: enum Default:
ACTIVE Possible values:
ACTIVE , DRAFT , PAUSED |
frequency_cap
optional
|
The maximum number of times an ad could be delivered to a user. Note: Only supported for Type: int Example: |
standard_delivery
optional
|
Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Type: boolean Default:
true Possible values:
true , false |
total_budget_amount_local_micro
optional
|
The total budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000. Type: long Example: |
Example Request¶
POST https://ads-api.twitter.com/4/accounts/18ce54d4x5t/campaigns?funding_instrument_id=lygyi&name=demo&start_time=2017-07-05&daily_budget_amount_local_micro=140000000&entity_status=PAUSED
Example Response¶
{
"data": {
"name": "demo",
"start_time": "2017-07-05T00:00:00Z",
"reasons_not_servable": [
"PAUSED_BY_ADVERTISER",
"INCOMPLETE"
],
"servable": false,
"daily_budget_amount_local_micro": 140000000,
"end_time": null,
"funding_instrument_id": "lygyi",
"duration_in_days": null,
"standard_delivery": true,
"total_budget_amount_local_micro": null,
"id": "8slvg",
"entity_status": "PAUSED",
"account_id": "18ce54d4x5t",
"frequency_cap": null,
"currency": "USD",
"created_at": "2017-06-23T01:59:12Z",
"updated_at": "2017-06-23T01:59:12Z",
"deleted": false
},
"request": {
"params": {
"name": "demo",
"start_time": "2017-07-05T00:00:00Z",
"daily_budget_amount_local_micro": 140000000,
"funding_instrument_id": "lygyi",
"entity_status": "PAUSED",
"account_id": "18ce54d4x5t"
}
}
}
POST batch/accounts/:account_id/campaigns¶
Allows the batch creation of new campaigns with a single request.
Batch Requests
- The current maximum batch size is 20.
- 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 campaign parameter) are shown in
the response under the
operation_errors
object.
Resource URL¶
https://ads-api.twitter.com/4/batch/accounts/:account_id/campaigns
Parameters¶
Name | Description |
---|---|
operation_type
required
|
The per item operation type being performed. Type: enum Possible values: |
params
required
|
A JSON object containing all the parameters for the campaign objects. For a list of required and optional campaign parameters, see here. |
Example Request¶
POST 'Content-Type: application/json' https://ads-api.twitter.com/4/batch/accounts/18ce54d4x5t/campaigns
[
{
"operation_type":"Create",
"params":{
"start_time":"2017-07-10",
"name":"batch campaigns",
"funding_instrument_id":"lygyi",
"daily_budget_amount_local_micro":140000000,
"entity_status":"PAUSED"
}
}
]
Example Response¶
{
"data": [
{
"name": "batch campaigns",
"start_time": "2017-07-10T00:00:00Z",
"reasons_not_servable": [
"PAUSED_BY_ADVERTISER",
"INCOMPLETE"
],
"servable": false,
"daily_budget_amount_local_micro": 140000000,
"end_time": null,
"funding_instrument_id": "lygyi",
"duration_in_days": null,
"standard_delivery": true,
"total_budget_amount_local_micro": null,
"id": "8yn7m",
"entity_status": "PAUSED",
"account_id": "18ce54d4x5t",
"frequency_cap": null,
"currency": "USD",
"created_at": "2017-07-07T17:28:50Z",
"updated_at": "2017-07-07T17:28:50Z",
"deleted": false
}
],
"request": [
{
"params": {
"name": "batch campaigns",
"start_time": "2017-07-10T00:00:00Z",
"funding_instrument_id": "lygyi",
"daily_budget_amount_local_micro": 140000000,
"entity_status": "PAUSED",
"account_id": "18ce54d4x5t"
},
"operation_type": "Create"
}
]
}
PUT accounts/:account_id/campaigns/:campaign_id¶
Update the specified campaign associated with the current account.
Resource URL¶
https://ads-api.twitter.com/4/accounts/:account_id/campaigns/:campaign_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: |
campaign_id
required
|
A reference to the campaign you are operating with in the request. Type: string Example: |
daily_budget_amount_local_micro
optional
|
The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time. Note: This should be less than or equal to the
Type: long Example: |
end_time
optional
|
The time, expressed in ISO 8601, that the campaign will end. Type: string Example: |
entity_status
optional
|
The campaign status. Type: enum Possible values: |
duration_in_days
optional
|
The time period within which the Type: int Possible values: |
frequency_cap
optional
|
The maximum number of times an ad could be delivered to a user. Type: int Example: |
name
optional
|
The name for the campaign. Type: string Example: |
standard_delivery
optional
|
Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Type: boolean Default:
true Possible values:
true , false |
start_time
optional
|
The time, expressed in ISO 8601, that the campaign will begin. Type: string Example: |
total_budget_amount_local_micro
optional
|
The total budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000. Type: long Example: |
Example Request¶
PUT https://ads-api.twitter.com/4/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000
Example Response¶
{
"data": {
"name": "batch campaigns",
"start_time": "2017-06-30T00:00:00Z",
"reasons_not_servable": [
"PAUSED_BY_ADVERTISER",
"INCOMPLETE"
],
"servable": false,
"daily_budget_amount_local_micro": null,
"end_time": null,
"funding_instrument_id": "lygyi",
"duration_in_days": null,
"standard_delivery": true,
"total_budget_amount_local_micro": 140000000,
"id": "8wku2",
"entity_status": "PAUSED",
"account_id": "18ce54d4x5t",
"frequency_cap": null,
"currency": "USD",
"created_at": "2017-06-30T21:17:16Z",
"updated_at": "2017-07-04T21:41:49Z",
"deleted": false
},
"request": {
"params": {
"campaign_id": "8wku2",
"total_budget_amount_local_micro": 140000000,
"account_id": "18ce54d4x5t"
}
}
}
DELETE accounts/:account_id/campaigns/:campaign_id¶
Delete the specified campaign belonging to the current account.
Note: Deleting a campaign is not reversible and subsequent attempts to delete the resource will return HTTP 404.
Resource URL¶
https://ads-api.twitter.com/4/accounts/:account_id/campaigns/:campaign_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: |
campaign_id
required
|
A reference to the campaign you are operating with in the request. Type: string Exampple: |
Example Request¶
DELETE https://ads-api.twitter.com/4/accounts/18ce54d4x5t/campaigns/8yn7m
Example Response¶
{
"data": {
"name": "batch campaigns",
"start_time": "2017-07-10T00:00:00Z",
"reasons_not_servable": [
"DELETED"
],
"servable": false,
"daily_budget_amount_local_micro": 140000000,
"end_time": null,
"funding_instrument_id": "lygyi",
"duration_in_days": null,
"standard_delivery": true,
"total_budget_amount_local_micro": null,
"id": "8yn7m",
"entity_status": "PAUSED",
"account_id": "18ce54d4x5t",
"frequency_cap": null,
"currency": "USD",
"created_at": "2017-07-07T17:28:50Z",
"updated_at": "2017-08-09T07:35:30Z",
"deleted": true
},
"request": {
"params": {
"campaign_id": "8yn7m",
"account_id": "18ce54d4x5t"
}
}
}