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/3/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: 18ce54d4x5t
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: 8wku2
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: 8x7v00oow
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: lygyi
sort_by
optional

Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional

Include the total_count response attribute.

Note: This parameter will be ignored if cursor is specified.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.twitter.com/3/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/3/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: 18ce54d4x5t
campaign_id
required

A reference to the campaign you are operating with in the request.

Type: string

Example: 8wku2
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/3/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/3/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: 18ce54d4x5t
funding_instrument_id
required

The identifier for the funding instrument to create the campaign under.

Type: string

Example: lygyi
name
required

The name for the campaign.

Type: string

Example: demo
start_time
required

The time, expressed in ISO 8601, that the campaign will begin.

Type: string

Example: 2017-07-05T00:00:00Z
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 total_budget_amount_local_micro.

Type: long

Example: 5500000
duration_in_days
optional

The time period within which the frequency_cap is achieved.

Type: int

Possible values: 1, 7, 30
end_time
optional

The time, expressed in ISO 8601, that the campaign will end.

Type: string

Example: 2017-10-05T00:00:00Z
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 AWARENESS, TWEET_ENGAGEMENTS, VIDEO_VIEWS, and VIDEO_VIEWS_PREROLL objectives.

Type: int

Example: 5
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: 37500000

Example Request

POST https://ads-api.twitter.com/3/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 of application/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/3/batch/accounts/:account_id/campaigns

Parameters

Name Description
operation_type
required

The per item operation type being performed.

Type: enum

Possible values: Create, Delete, Update
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/3/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/3/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: 18ce54d4x5t
campaign_id
required

A reference to the campaign you are operating with in the request.

Type: string

Example: 8wku2
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 total_budget_amount_local_micro.

Type: long

Example: 5500000
end_time
optional

The time, expressed in ISO 8601, that the campaign will end.

Type: string

Example: 2017-10-05T00:00:00Z
entity_status
optional

The campaign status.

Type: enum

Possible values: ACTIVE, PAUSED
duration_in_days
optional

The time period within which the frequency_cap is achieved.

Type: int

Possible values: 1, 7, 30
frequency_cap
optional

The maximum number of times an ad could be delivered to a user.

Type: int

Example: 5
name
optional

The name for the campaign.

Type: string

Example: demo
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: 2017-07-05T00:00:00Z
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: 140000000

Example Request

PUT https://ads-api.twitter.com/3/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/3/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: 18ce54d4x5t
campaign_id
required

A reference to the campaign you are operating with in the request.

Type: string

Exampple: 8yn7m

Example Request

DELETE https://ads-api.twitter.com/3/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"
    }
  }
}