Campaigns
campaigns

Campaigns

GET accounts/:account_id/campaigns

Retrieve details for some or all campaigns associated with the current account.

Resource URL

https://ads-api.x.com/12/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

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

q
optional

An optional query to scope resource by name.

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: created_at-asc

with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_draft
optional

Include draft campaigns 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 and cursor are exclusive.

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.x.com/12/accounts/18ce54d4x5t/campaigns?campaign_ids=8wku2

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "campaign_ids": [
        "8wku2"
      ]
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "test",
      "budget_optimization": "CAMPAIGN",
      "reasons_not_servable": [
        "PAUSED_BY_ADVERTISER",
        "INCOMPLETE"
      ],
      "servable": false,
      "purchase_order_number": null,
      "effective_status": "UNKNOWN",
      "daily_budget_amount_local_micro": 10000000,
      "funding_instrument_id": "lygyi",
      "duration_in_days": null,
      "standard_delivery": false,
      "total_budget_amount_local_micro": null,
      "id": "8wku2",
      "entity_status": "PAUSED",
      "frequency_cap": null,
      "currency": "USD",
      "created_at": "2022-06-03T21:38:07Z",
      "updated_at": "2022-06-03T21:38:07Z",
      "deleted": false
    }
  ]
}

GET accounts/:account_id/campaigns/:campaign_id

Retrieve a specific campaign associated with the current account.

Resource URL

https://ads-api.x.com/12/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.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2

Example Response

{
  "request": {
    "params": {
      "campaign_id": "8wku2",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "test",
    "budget_optimization": "CAMPAIGN",
    "reasons_not_servable": [
      "PAUSED_BY_ADVERTISER",
      "INCOMPLETE"
    ],
    "servable": false,
    "purchase_order_number": null,
    "effective_status": "UNKNOWN",
    "daily_budget_amount_local_micro": 10000000,
    "funding_instrument_id": "lygyi",
    "duration_in_days": null,
    "standard_delivery": false,
    "total_budget_amount_local_micro": null,
    "id": "8wku2",
    "entity_status": "PAUSED",
    "frequency_cap": null,
    "currency": "USD",
    "created_at": "2022-06-03T21:38:07Z",
    "updated_at": "2022-06-03T21:38:07Z",
    "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.x.com/12/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. Maximum length: 255 characters.

Type: string

Example: demo

budget_optimization
optional

Select the type of budget optimization to be applied

Type: enum

Default: CAMPAIGN
Possible values: CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro
sometimes required

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.

Note: This should be less than or equal to the total_budget_amount_local_micro and is required for most Funding Insturment types.

Type: long

Example: 5500000

entity_status
optional

The campaign status.

Type: enum

Default: ACTIVE
Possible values: ACTIVE, DRAFT, PAUSED
purchase_order_number
optional

The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters.

Type: string

Example: D00805843

standard_delivery
optional

Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Only available when budget_optimization is set to CAMPAIGN.

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.x.com/12/accounts/18ce54d4x5t/campaigns?funding_instrument_id=lygyi&name=demo&daily_budget_amount_local_micro=140000000&entity_status=PAUSED&budget_optimization=CAMPIAGN&standard_delivery=false

Example Response

{
  "request": {
    "params": {
      "name": "demo",
      "budget_optimization": "CAMPAIGN",
      "daily_budget_amount_local_micro": 140000000,
      "funding_instrument_id": "lygyi",
      "standard_delivery": false,
      "entity_status": "PAUSED",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "demo",
    "budget_optimization": "CAMPAIGN",
    "reasons_not_servable": [
      "PAUSED_BY_ADVERTISER",
      "INCOMPLETE"
    ],
    "servable": false,
    "purchase_order_number": null,
    "effective_status": "UNKNOWN",
    "daily_budget_amount_local_micro": 140000000,
    "funding_instrument_id": "lygyi",
    "duration_in_days": null,
    "standard_delivery": false,
    "total_budget_amount_local_micro": null,
    "id": "hwtbm",
    "entity_status": "PAUSED",
    "frequency_cap": null,
    "currency": "USD",
    "created_at": "2022-06-03T21:38:07Z",
    "updated_at": "2022-06-03T21:38:07Z",
    "deleted": false
  }
}

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 40.
  • 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.x.com/12/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.x.com/12/batch/accounts/18ce54d4x5t/campaigns

[  
  {  
    "operation_type":"Create",
    "params":{  
      "name":"batch campaigns",
      "funding_instrument_id":"lygyi",
      "daily_budget_amount_local_micro":140000000,
      "entity_status":"PAUSED",
      "budget_optimization":"CAMPAIGN"
    }
  }
]

Example Response

{
  "data": [
    {
      "name": "batch campaigns",
      "budget_optimization": "CAMPAIGN",
      "reasons_not_servable": [
        "PAUSED_BY_ADVERTISER",
        "INCOMPLETE"
      ],
      "servable": false,
      "purchase_order_number": null,
      "effective_status": "UNKNOWN",
      "daily_budget_amount_local_micro": 140000000,
      "funding_instrument_id": "lygyi",
      "duration_in_days": null,
      "standard_delivery": false,
      "total_budget_amount_local_micro": null,
      "id": "8yn7m",
      "entity_status": "PAUSED",
      "frequency_cap": null,
      "currency": "USD",
      "created_at": "2022-06-03T21:38:07Z",
      "updated_at": "2022-06-03T21:38:07Z",
      "deleted": false
    }
  ],
  "request": [
    {
      "params": {
        "name": "batch campaigns",
        "funding_instrument_id": "lygyi",
        "daily_budget_amount_local_micro": 140000000,
        "entity_status": "PAUSED",
        "budget_optimization":"CAMPAIGN",
        "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.x.com/12/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

budget_optimization
optional

Select the type of budget optimization to be applied

Type: enum

Default: CAMPAIGN
Possible values: CAMPAIGN, LINE_ITEM
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

entity_status
optional

The campaign status.

Type: enum

Possible values: ACTIVE, PAUSED

name
optional

The name for the campaign. Maximum length: 255 characters.

Type: string

Example: demo

purchase_order_number
optional

The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters.

Type: string

Example: D00805843

standard_delivery
optional

Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Only available when budget_optimization is set to CAMPAIGN.

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: 140000000

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000

Example Response

{
  "request": {
    "params": {
      "campaign_id": "8wku2",
      "daily_budget_amount_local_micro": 140000000,
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "test",
    "budget_optimization": "CAMPAIGN",
    "reasons_not_servable": [
      "PAUSED_BY_ADVERTISER",
      "INCOMPLETE"
    ],
    "servable": false,
    "purchase_order_number": null,
    "effective_status": "UNKNOWN",
    "daily_budget_amount_local_micro": 140000000,
    "funding_instrument_id": "lygyi",
    "duration_in_days": null,
    "standard_delivery": false,
    "total_budget_amount_local_micro": null,
    "id": "8wku2",
    "entity_status": "PAUSED",
    "frequency_cap": null,
    "currency": "USD",
    "created_at": "2022-06-03T21:38:07Z",
    "updated_at": "2022-06-03T21:53:54Z",
    "deleted": false
  }
}

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.x.com/12/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.x.com/12/accounts/18ce54d4x5t/campaigns/8yn7m

Example Response

{
  "request": {
    "params": {
      "campaign_id": "8yn7m",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "test",
    "budget_optimization": "CAMPAIGN",
    "reasons_not_servable": [],
    "servable": null,
    "purchase_order_number": null,
    "effective_status": "RUNNING",
    "daily_budget_amount_local_micro": 140000000,
    "funding_instrument_id": "lygyi",
    "duration_in_days": null,
    "standard_delivery": false,
    "total_budget_amount_local_micro": null,
    "id": "8yn7m",
    "entity_status": "PAUSED",
    "frequency_cap": null,
    "currency": "USD",
    "created_at": "2022-06-03T21:38:07Z",
    "updated_at": "2022-06-03T21:56:35Z",
    "deleted": true
  }
}