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

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.

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

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
  }
}