X Ads API

https://docs.x.com/x-ads-api/
Admin
X Ads API enables developers to programmatically manage ad campaigns, audiences, creatives, and...
Tokens:178,151
Snippets:1,142
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Retrieve Account Media List

Source: https://docs.x.com/x-ads-api/creatives/reference

Example JSON response for a GET request to fetch account media details.

```json
{
  "request": {
    "params": {
      "account_media_ids": [
        "3wpx"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_id": "13_771791717175468032",
      "media_url": null,
      "creative_type": "PREROLL",
      "id": "3wpx",
      "created_at": "2016-09-02T19:27:52Z",
      "updated_at": "2016-09-02T19:27:52Z",
      "deleted": false
    }
  ]
}
```

--------------------------------

### Retrieve Targeting Suggestions

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example response for the GET accounts/:account_id/targeting_suggestions endpoint.

```json
    {
      "data": [
        {
          "suggestion_type": "KEYWORD",
          "suggestion_value": "devs"
        },
        {
          "suggestion_type": "KEYWORD",
          "suggestion_value": "software"
        }
      ],
      "request": {
        "params": {
          "suggestion_type": "KEYWORD",
          "targeting_values": [
            "developers"
          ],
          "count": 2,
          "account_id": "18ce54d4x5t"
        }
      }
    }
```

--------------------------------

### Retrieve Promoted Accounts Example

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example request and response for fetching promoted account data.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?promoted_account_ids=19pl2
```

```json
{
      "request": {
        "params": {
          "promoted_account_ids": [
            "19pl2"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "9bpb2",
          "user_id": "756201191646691328",
          "id": "19pl2",
          "entity_status": "ACTIVE",
          "created_at": "2017-07-05T05:54:13Z",
          "updated_at": "2017-07-05T05:54:13Z",
          "approval_status": "ACCEPTED",
          "deleted": false
        }
      ]
    }
```

--------------------------------

### Get Tweet Previews Request

Source: https://docs.x.com/x-ads-api/creatives/reference

Example GET request to retrieve previews for published tweets.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet_previews?tweet_ids=1122911801354510336,1102836745790316550&tweet_type=PUBLISHED
```

--------------------------------

### Retrieve Line Item Placements

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example response for a GET request to the line_items/placements endpoint filtered by product type.

```json
    {
      "data": [
        {
          "product_type": "PROMOTED_ACCOUNT",
          "placements": [
            [
              "ALL_ON_TWITTER"
            ],
            [
              "TWITTER_TIMELINE"
            ]
          ]
        }
      ],
      "request": {
        "params": {
          "product_type": "PROMOTED_ACCOUNT"
        }
      }
    }
```

--------------------------------

### List Cards Request

Source: https://docs.x.com/x-ads-api/creatives/reference

Example of a GET request to retrieve a list of cards.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards?count=1
```

--------------------------------

### Retrieve Media Library Object Details

Source: https://docs.x.com/x-ads-api/creatives/reference

Example JSON response showing the structure of a media library object retrieved via GET.

```json
{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "13_909110614026444802"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 39973,
    "name": null,
    "file_name": "buildings https://t.co/xFdzrHM5QG",
    "description": null,
    "media_url": "https://video.twimg.com/amplify_video/909110614026444802/vid/1280x720/mfahmfkKVjjk1nGm.mp4",
    "media_category": "AMPLIFY_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/909110614026444802/img/QZUNoaiCia0UFNrw.jpg",
    "poster_media_key": "3_909110614026444802",
    "media_key": "13_909110614026444802",
    "created_at": "2017-09-16T17:43:55Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "buildings",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-09-27T13:04:00Z",
    "deleted": false
  }
}
```

--------------------------------

### Retrieve Campaign Details Request

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example of a GET request to fetch a specific campaign by account and campaign ID.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2
```

--------------------------------

### Retrieve Promotable Users Example

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example request and response for fetching promotable user details for a specific account.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s
```

```json
{
      "request": {
        "params": {
          "promotable_user_ids": [
            "l310s"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "user_id": "756201191646691328",
          "id": "l310s",
          "created_at": "2016-07-21T22:42:09Z",
          "updated_at": "2016-07-21T22:42:09Z",
          "deleted": false,
          "promotable_user_type": "FULL"
        }
      ]
    }
```

--------------------------------

### Retrieve Advertiser Business Categories

Source: https://docs.x.com/x-ads-api/campaign-management

Example response for the GET request to fetch available advertiser business categories.

```json
GET https://ads-api.x.com/8/advertiser\_business\_categories

{
  "request": {
    "params": {}
  },
  "next_cursor": null,
  "data": [
    {
      "id": "1jl",
      "name": "Consumer Packaged Goods",
      "iab_categories": [
        "IAB9-26",
        "IAB9-18",
        "IAB9-29",
        "IAB9-1",
        "IAB9-8",
        "IAB9-22",
        "IAB6",
        "IAB9-5",
        "IAB9-12",
        "IAB9-11",
        "IAB9-23",
        "IAB9-14",
        "IAB4",
        "IAB9-25",
        "IAB9-17",
        "IAB23",
        "IAB9-24",
        "IAB9-13",
        "IAB16",
        "IAB9-4",
        "IAB9-9",
        "IAB9-20",
        "IAB22",
        "IAB9-28",
        "IAB9-27",
        "IAB9-16",
        "IAB9-31",
        "IAB9-3",
        "IAB9-19",
        "IAB10",
        "IAB9-2",
        "IAB9-6",
        "IAB9-21",
        "IAB9-10",
        "IAB9-15"
      ]
    },
    {
      "id": "1jm",
      "name": "Health & Pharma",
      "iab_categories": [
        "IAB7"
      ]
    },
    {
      "id": "1jn",
      "name": "Alcohol",
      "iab_categories": [
        "IAB8-5",
        "IAB8-18"
      ]
    },
    {
      "id": "1jo",
      "name": "Dining",
      "iab_categories": [
        "IAB8-10",
        "IAB8-8",
        "IAB8-7",
        "IAB8-15",
        "IAB8-3",
        "IAB8-4",
        "IAB8-1",
        "IAB8-16",
        "IAB8-12",
        "IAB8-13",
        "IAB8-17",
        "IAB8-11",
        "IAB8-6",
        "IAB8-9",
        "IAB8-2",
        "IAB8-14"
      ]
    },
    {
      "id": "1jp",
      "name": "Financial Services",
      "iab_categories": [
        "IAB3",
        "IAB13",
        "IAB21"
      ]
    },
    {
      "id": "1jq",
      "name": "Retail",
      "iab_categories": [
        "IAB18"
      ]
    },
    {
      "id": "1jr",
      "name": "Travel",
      "iab_categories": [
        "IAB20"
      ]
    },
    {
      "id": "1js",
      "name": "Gaming",
      "iab_categories": [
        "IAB9-30"
      ]
    },
    {
      "id": "1jt",
      "name": "Technology",
      "iab_categories": [
        "IAB19-22",
        "IAB19-13",
        "IAB19-4",
        "IAB19-33",
        "IAB19-26",
        "IAB19-3",
        "IAB19-16",
        "IAB19-9",
        "IAB19-32",
        "IAB19-25",
        "IAB19-30",
        "IAB19-36",
        "IAB19-21",
        "IAB5",
        "IAB19-12",
        "IAB19-28",
        "IAB19-17",
        "IAB19-8",
        "IAB19-7",
        "IAB19-24",
        "IAB15",
        "IAB19-11",
        "IAB19-31",
        "IAB19-20",
        "IAB19-15",
        "IAB19-1",
        "IAB19-35",
        "IAB19-29",
        "IAB19-34",
        "IAB19-23",
        "IAB19-2",
        "IAB19-5",
        "IAB19-14",
        "IAB19-27",
        "IAB19-10",
        "IAB19-19"
      ]
    },
    {
      "id": "1ju",
      "name": "Telecommunication",
      "iab_categories": [
        "IAB19-6",
        "IAB19-18"
      ]
    },
    {
      "id": "1jv",
      "name": "Auto",
      "iab_categories": [
        "IAB2"
      ]
    },
    {
      "id": "1jw",
      "name": "Media & Entertainment",
      "iab_categories": [
        "IAB14-8",
        "IAB14-4",
        "IAB1-5",
        "IAB14-7",
        "IAB1-7",
        "IAB17",
        "IAB14-3",
        "IAB1-1",
        "IAB12",
        "IAB1-6",
        "IAB25-1",
        "IAB1-2",
        "IAB14-2",
        "IAB14-6",
        "IAB1-3",
        "IAB1-4",
        "IAB14-5"
      ]
    },
    {
      "id": "1jx",
      "name": "Politics",
      "iab_categories": [
        "IAB11-4"
      ]
    },
    {
      "id": "1jy",
      "name": "Gambling",
      "iab_categories": [
        "IAB9-7"
      ]
    },
    {
      "id": "1jz",
      "name": "Dating",
      "iab_categories": [
        "IAB14-1"
      ]
    },
    {
      "id": "1k0",
      "name": "Non-Profit",
      "iab_categories": [
        "IAB11-1",
        "IAB11-2",
        "IAB11-3",
        "IAB11-5"
      ]
    }
  ]
}
```

--------------------------------

### List Video Conversation Cards Request

Source: https://docs.x.com/x-ads-api/creatives/reference

Example GET request to retrieve video conversation cards for a specific account.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?card_ids=5a86h
```

--------------------------------

### Retrieve Tax Settings Response Example

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example JSON response structure returned when querying or updating account tax settings.

```json
{
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "address_name": "ABC Co."
        }
      },
      "data": {
        "tax_id": "GB896391250",
        "address_city": "London",
        "business_relationship": "SELF",
        "address_street1": "21 March St",
        "address_last_name": null,
        "address_company": "ABC, Co.",
        "tax_category": "BUSINESS_WITH_VAT",
        "address_postal_code": "SW1A 1AA",
        "bill_to": "NOT_SET",
        "address_region": "London",
        "address_country": "GB",
        "address_first_name": null,
        "invoice_jurisdiction": "NOT_SET",
        "address_street2": null,
        "address_email": null
      }
    }
```

--------------------------------

### Example GET Accounts Response

Source: https://docs.x.com/x-ads-api/getting-started

The JSON structure returned by the accounts endpoint, containing details for authorized ad accounts.

```json
{
  "request": {
    "params": {}
  },
  "data": [
   {
    "name": "Furni",
    "business_name": null,
    "timezone": "America/Los_Angeles",
    "timezone_switch_at": "2016-04-06T07:00:00Z",
    "id": "18ce54ayf0z",
    "created_at": "2016-04-07T14:40:15Z",
    "salt": "b88939e5cabbca720159cb3659d73c06",
    "updated_at": "2017-02-08T08:49:53Z",
    "business_id": null,
    "approval_status": "ACCEPTED",
    "deleted": false
     }
   ]
}
```

--------------------------------

### Retrieve Account History Example

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example response structure for the account history endpoint. This endpoint is currently in beta and requires allowlisting.

```json
{
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "CAMPAIGN",
          "entity_id": "fc3h5",
          "count": 1
        }
      },
      "next_cursor": "1r2407sb4lc",
      "data": [
        {
          "change_by": {
            "user_id": "982978172",
            "platform": "API_OTHER"
          },
          "changes": {},
          "change_time": "2021-04-02T20:55:42Z",
          "entity_id": "fc3h5",
          "entity": "CAMPAIGN",
          "entity_data": {
            "name": "test_campaign",
            "start_time": "2021-04-02T18:59:11Z",
            "purchase_order_number": null,
            "daily_budget_amount_local_micro": 100000000,
            "end_time": null,
            "duration_in_days": null,
            "standard_delivery": true,
            "total_budget_amount_local_micro": 100000000,
            "entity_status": "ACTIVE",
            "frequency_cap": null,
            "created_at": "2021-04-02T20:55:42Z",
            "updated_at": "2021-04-02T20:55:42Z",
            "deleted": false
          },
          "change_type": "CREATE"
        }
      ]
    }
```

--------------------------------

### Manual Product Set Response

Source: https://docs.x.com/x-ads-api/catalog-management/reference

Example response returned after successfully creating a manual product set.

```json
{
  "request": {
    "params": {
      "product_catalog_id": "1569782857975087104",
      "name": "manual API product set",
      "type": "MANUAL",
      "product_keys": [
        "1569784751351013380"
      ]
    }
  },
  "data": {
    "name": "manual API product set",
    "description": null,
    "product_ids": [
      "sdkljsdijf"
    ],
    "processing_status": "DONE",
    "id": "1573806483589849088",
    "filters": [],
    "type": "MANUAL"
  }
}
```

--------------------------------

### Example Response for Media Library List

Source: https://docs.x.com/x-ads-api/creatives/reference

A sample JSON response showing a paginated list of media library objects.

```json
{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "count": 1
    }
  },
  "data": [
    {
      "tweeted": true,
      "name": null,
      "file_name": "coffee https://t.co/4tcPU9XUon",
      "media_url": "https://pbs.twimg.com/media/DJvnJf_UEAAXnzC.jpg",
      "media_category": "TWEET_IMAGE",
      "media_key": "3_908573900237180928",
      "created_at": "2017-09-15T06:11:12Z",
      "media_status": "TRANSCODE_COMPLETED",
      "media_type": "IMAGE",
      "updated_at": "2017-11-16T06:00:01Z",
      "deleted": false
    }
  ],
  "next_cursor": "c-1"
}
```

--------------------------------

### Retrieve TV Show Targeting Criteria

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example response for the GET targeting_criteria/tv_shows endpoint.

```json
    {
      "data": [
        {
          "name": "NewsWatch",
          "targeting_value": 10027243420,
          "genre": "PAID",
          "locales": [
            {
              "language": "en",
              "country": "US"
            }
          ]
        }
      ],
      "next_cursor": "c-22838-zdQDJrTxSvOYfQOhb2IlGQ",
      "request": {
        "params": {
          "locale": {
            "countryCode": "US",
            "languageCode": "en"
          },
          "count": 1,
          "q": "news"
        }
      }
    }
```

--------------------------------

### Create a Campaign

Source: https://docs.x.com/x-ads-api/campaign-management

Create a new campaign by providing the funding instrument ID, name, and budget parameters.

```bash
twurl -H ads-api.x.com -d "funding_instrument_id=yyyy&name=My First Campaign&total_budget_amount_local_micro=500000000&daily_budget_amount_local_micro=50000000" /9/accounts/xxxxxx/campaigns
```

--------------------------------

### Retrieve a Poll Card

Source: https://docs.x.com/x-ads-api/creatives/reference

Example GET request to fetch details of a specific poll card.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i8t
```

--------------------------------

### Retrieve Single Card Request

Source: https://docs.x.com/x-ads-api/creatives/reference

Example of a GET request to retrieve details for a specific card.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264
```

--------------------------------

### Retrieve Product Catalog Products

Source: https://docs.x.com/x-ads-api/catalog-management/reference

Example request and response for fetching products from a specific catalog.

```json
GET https://ads-api.x.com/12/product_catalogs/1547080201384865792/products?count=1
```

```json
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792",
      "count": 1
    }
  },
  "next_cursor": "1547080787865939970",
  "data": [
    {
      "inventory": 5,
      "custom_label_2": null,
      "item_group_key": null,
      "additional_image_link": null,
      "size": null,
      "mobile_link": null,
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
      "price": "20.00 USD",
      "gtin": null,
      "age_group": "teen",
      "availability": "in stock",
      "product_type": "",
      "color": null,
      "custom_label_3": null,
      "item_group_id": null,
      "brand": "X",
      "product_key": "1547080787865939969",
      "mpn": null,
      "id": "123abc",
      "custom_label_4": null,
      "condition": "new",
      "custom_label_0": null,
      "sale_price": null,
      "custom_label_1": null,
      "link": "https://www.x.com/twtr_blue",
      "sale_price_effective_date": null,
      "image_link": "https://t.co/jeans_1.jpg",
      "title": "My shoes",
      "google_product_category": "Apparel & Accessories > Shoes",
      "gender": "female"
    }
  ]
}
```

--------------------------------

### Retrieve Curated Categories Response

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example JSON response structure for the GET accounts/:account_id/curated_categories endpoint.

```json
{
  "name": "Men’s Culture + Lifestyle",
  "description": "Run next to content from a set of handles curated based on their follower profiles to help you reach a majority male audience, including some of the top handles sharing technology, news, and lifestyle content.",
  "country_codes": [
    "US"
  ],
  "publisher_user_ids": [
    "17764377",
    "61933836",
    "28370738",
    "3224616765",
    "22819823",
    "18927441",
    "734826612684783616",
    "14372486",
    "7157132",
    "15764136",
    "590316679",
    "7302282",
    "895014043932540928",
    "7517222",
    "3489420013",
    "14063426",
    "72665816",
    "214201922",
    "14980903",
    "22199141",
    "21272440",
    "25319414",
    "119593082",
    "4760694445",
    "765905855195803648",
    "238431491",
    "22178780",
    "241544156",
    "25093616",
    "16877611",
    "22146985",
    "368703433",
    "14342661",
    "415605847",
    "2181233851",
    "890891",
    "15764001",
    "614754689",
    "18479513",
    "23508439",
    "348590880"
  ],
  "id": "8tujj1ep7t34",
  "created_at": "2019-08-15T20:49:47Z",
  "updated_at": "2021-03-09T20:39:00Z",
  "videos_monetized_in_last_thirty_days": 1330
},
{
  "name": "Women’s Culture + Lifestyle",
  "description": "Run next to content from a set of handles curated based on their follower profiles to help you reach a majority female audience, including some of the top handles sharing pop culture, news, and lifestyle content.",
  "country_codes": [
    "US"
  ],
  "publisher_user_ids": [
    "23482952",
    "20177423",
    "19074134",
    "15566901",
    "32469566",
    "19784831",
    "16145224",
    "16932962",
    "14934818",
    "29730065",
    "24190981",
    "30278532",
    "15846407",
    "24994219",
    "23993734",
    "40965341",
    "16312576",
    "75094638",
    "549673665",
    "18806753",
    "75306892",
    "1482663290",
    "31181674",
    "971407531972186112",
    "4020532937",
    "25087685",
    "22515362",
    "80943051",
    "19247844",
    "15279429",
    "16824090",
    "20710809",
    "979831113655996416",
    "32432308",
    "19472585",
    "25589776",
    "739963476370673665",
    "20188834",
    "926269727663673349"
  ],
  "id": "8tujl1p3yn0g",
  "created_at": "2019-08-15T20:50:24Z",
  "updated_at": "2021-03-09T20:17:53Z",
  "videos_monetized_in_last_thirty_days": 1365
},
{
  "name": "Light-Hearted",
  "description": "Run next to a list of handles curated for the volume of positive, feel-good content and conversation they’ve consistently generated on X.",
  "country_codes": [
    "US"
  ],
  "publisher_user_ids": [
    "20177423",
    "22449367",
    "9695312",
    "19074134",
    "4805771380",
    "32469566",
    "1212860112047460352",
    "16402507",
    "16932962",
    "14934818",
    "17446621",
    "29730065",
    "15846407",
    "1604444052",
    "180066380",
    "16312576",
    "549673665",
    "18806753",
    "16211434",
    "545336345",
    "971407531972186112",
    "4020532937",
    "833612154",
    "22515362",
    "20710809",
    "32432308",
    "774311630",
    "3073349892",
    "926269727663673349"
  ],
  "id": "9fg8gmz96qdg",
  "created_at": "2020-03-20T19:37:44Z",
  "updated_at": "2021-03-09T19:57:40Z",
  "videos_monetized_in_last_thirty_days": 1395
}
```

--------------------------------

### Create Media Library Object Response

Source: https://docs.x.com/x-ads-api/creatives/reference

Example JSON response returned after successfully associating a media object with an account via POST.

```json
{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "3_931236738554519552"
    }
  },
  "data": {
    "tweeted": false,
    "name": null,
    "file_name": null,
    "media_url": "https://pbs.twimg.com/media/DOxq4TtV4AAlvh_.jpg",
    "media_category": "TWEET_IMAGE",
    "media_key": "3_931236738554519552",
    "created_at": "2017-11-16T19:05:14Z",
    "media_status": "TRANSCODE_COMPLETED",
    "media_type": "IMAGE",
    "updated_at": "2017-11-16T19:05:23Z",
    "deleted": false
  }
}
```

--------------------------------

### GET accounts/:account_id/curated_categories response

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example JSON response containing curated category data for an account.

```json
        {
          "videos_monetized_in_last_thirty_days": 448
        },
        {
          "name": "Baseball",
          "description": "Run next to the best of everyday baseball content including college teams, professional teams, and the top sports media handles sharing major baseball coverage.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "22016177",
            "22798877",
            "52803520",
            "20710218",
            "423532170",
            "28603812",
            "41144996",
            "22819823",
            "39389304",
            "252273678",
            "123307490",
            "2319354187",
            "41488578",
            "37947138",
            "302066953",
            "159143990",
            "35006336",
            "53178109",
            "40918816",
            "39682297",
            "39397148",
            "39419180",
            "53197137",
            "52863923",
            "21407926",
            "31164229",
            "19607400",
            "39392910",
            "241544156",
            "43024351",
            "37837907",
            "165764237",
            "69117905",
            "87673496",
            "23043294",
            "52824038",
            "52861612",
            "33137450",
            "30008146",
            "39367703",
            "21436663",
            "188575356",
            "40931019",
            "41468683",
            "40927173",
            "172742915"
          ],
          "id": "9lav5usxfmdc",
          "created_at": "2020-05-18T20:20:27Z",
          "updated_at": "2021-03-09T20:37:46Z",
          "videos_monetized_in_last_thirty_days": 190
        },
        {
          "name": "Esports Teams",
          "description": "Run next to the programming from the world’s best esports teams, covering both in-event coverage and other year-round complimentary programming.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "759527448757215232",
            "61933836",
            "477213534",
            "907193396049182720",
            "895382891408089089",
            "862708050116976640",
            "115038550",
            "3182089458",
            "4131266472",
            "1145702070961496065",
            "2262070855",
            "920664872786059264",
            "1035653581683220481",
            "14229141",
            "1101275970995027968",
            "20734751",
            "1452520626",
            "720303639277928448",
            "2853641871",
            "912696400571486208",
            "874362688939413504",
            "286505380",
            "892808605170245632",
            "875087838613733376",
            "238431491",
            "867053221940011014",
            "964529942",
            "1172506293174710272",
            "535756639",
            "2255226817",
            "1100825469853696000",
            "1122713320086220803",
            "1124064709295128581",
            "899858978418642944",
            "864977592532688896",
            "864476897106898944",
            "862770685445361665",
            "257268592"
          ],
          "id": "9ys3jz3ktreo",
          "created_at": "2020-10-01T20:02:35Z",
          "updated_at": "2021-03-09T20:36:20Z",
          "videos_monetized_in_last_thirty_days": 169
        },
        {
          "name": "Football ",
          "description": "Run next to the best of everyday football content including college teams, professional teams, and the top sports media handles sharing on and off-season football video.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "21790466",
            "53103297",
            "23642374",
            "817416193854283776",
            "43403778",
            "24179879",
            "26813914",
            "36375662",
            "33587536",
            "180884045",
            "16332223",
            "27902825",
            "180503626",
            "44468807",
            "18336787",
            "818431566",
            "22146282",
            "31126587",
            "40358743",
            "35865630",
            "16347506",
            "72665816",
            "33583496",
            "389038362",
            "36155311",
            "227342532",
            "2151130166",
            "26791995",
            "44666348",
            "24109979",
            "31504542",
            "713143",
            "423536031",
            "25545388",
            "59471027",
            "706923475",
            "19383279",
            "8824902",
            "1655877529",
            "18734310",
            "240734425",
            "17076218",
            "47964412",
            "2802184770",
            "19426729",
            "56443153",
            "23508439"
          ]
```

--------------------------------

### POST /product_catalogs

Source: https://docs.x.com/x-ads-api/catalog-management/reference

Create a new product catalog for the user.

```APIDOC
## POST https://ads-api.x.com/12/product_catalogs

### Description
Create a product catalog. One user can only create one catalog that holds all products.

### Method
POST

### Endpoint
https://ads-api.x.com/12/product_catalogs

### Parameters
#### Query Parameters
- **name** (string) - Required - Name of your product catalog.
- **user_id** (long) - Optional - A reference to the user you are operating with in the request.
```

--------------------------------

### Retrieve Tweet details request

Source: https://docs.x.com/x-ads-api/creatives/reference

Example GET request to fetch specific published tweets for an account.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets?tweet_ids=1166476031668015104&tweet_type=PUBLISHED&trim_user=true
```

--------------------------------

### Example Analytics Request

Source: https://docs.x.com/x-ads-api/analytics

A GET request to retrieve reach statistics for a specific account and funding instrument.

```text
GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/funding_instruments?funding_instrument_ids=lygyi&start_time=2026-05-19&end_time=2026-05-26
```

--------------------------------

### Create a Campaign via POST Request

Source: https://docs.x.com/x-ads-api/campaign-management

Example of a POST request to create a campaign with specified parameters and the resulting JSON response.

```json
POST https://ads-api.x.com/8/accounts/55w3kv/campaigns?name=test-curated-categories-api&funding\_instrument\_id=103hp9&start\_time=2021-02-10&entity\_status=PAUSED&daily\_budget\_amount\_local\_micro=55000000

{
  "request": {
    "params": {
      "name": "test-curated-categories-api",
      "start_time": "2021-02-10T00:00:00Z",
      "daily\_budget\_amount\_local\_micro": 55000000,
      "funding\_instrument\_id": "103hp9",
      "entity_status": "PAUSED",
      "account_id": "55w3kv"
    }
  },
  "data": {
    "name": "test-curated-categories-api",
    "start_time": "2021-02-10T00:00:00Z",
    "reasons\_not\_servable": [
      "EXPIRED",
      "PAUSED\_BY\_ADVERTISER",
      "FUNDING_PROBLEM"
    ],
    "servable": false,
    "purchase\_order\_number": null,
    "effective_status": "PAUSED",
    "daily\_budget\_amount\_local\_micro": 55000000,
    "end_time": null,
    "funding\_instrument\_id": "103hp9",
    "duration\_in\_days": null,
    "standard_delivery": true,
    "total\_budget\_amount\_local\_micro": null,
    "id": "f2rp3",
    "entity_status": "PAUSED",
    "frequency_cap": null,
    "currency": "USD",
    "created_at": "2021-02-08T23:55:38Z",
    "updated_at": "2021-02-08T23:55:38Z",
    "deleted": false
  }
}
```

--------------------------------

### Retrieve IAB Categories

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example response for a GET request retrieving a list of IAB categories with a specified count.

```json
{
      "data": [
        {
          "id": "IAB1",
          "parent_id": null,
          "name": "Arts & Entertainment"
        },
        {
          "id": "IAB1-1",
          "parent_id": "IAB1",
          "name": "Books & Literature"
        }
      ],
      "next_cursor": "uxa8",
      "request": {
        "params": {
          "count": 2
        }
      }
    }
```

--------------------------------

### Targeting Profile Setup

Source: https://docs.x.com/x-ads-api/campaign-management

Commands and responses for looking up location IDs and applying targeting criteria to a line item.

```bash
twurl -H ads-api.x.com "/9/targeting_criteria/locations?location_type=CITIES&q=San Francisco"
```

```json
{
  "data": [
    {
      "name": "San Francisco-Oakland-San Jose CA, US",
      "targeting_type": "LOCATION",
      "targeting_value": "5122804691e5fecc"
    }
  ],
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "location_type": "CITY",
      "q": "San Francisco"
    }
  }
}
```

```bash
twurl -H ads-api.x.com -X POST -d "line_item_id=yyyy&targeting_type=LOCATION&targeting_value=5122804691e5fecc" /9/accounts/xxxxxx/targeting_criteria
```

```json
{
  "data": {
    "created_at": "2015-02-09T00:00:15Z",
    "deleted": false,
    "id": "2u3be",
    "line_item_id": "yyyy",
    "name": "San Francisco-Oakland-San Jose CA, US",
    "targeting_type": "LOCATION",
    "targeting_value": "5122804691e5fecc",
    "updated_at": "2013-05-30T21:01:35Z"
  },
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "line_item_id": "yyyy",
      "targeting_type": "LOCATION",
      "targeting_value": "5122804691e5fecc"
    }
  }
}
```

```bash
twurl -H ads-api.x.com -X POST -d "line_item_id=yyyy&targeting_type=PHRASE_KEYWORD&targeting_value=grumpy cat" /9/accounts/xxxxxx/targeting_criteria
```

--------------------------------

### Create a Product Catalog

Source: https://docs.x.com/x-ads-api/catalog-management/reference

Creates a new product catalog for the merchant. Each user is limited to one catalog.

```json
POST https://ads-api.x.com/12/product_catalogs?name=catalog_123_abc_def
```

```json
{
  "request": {
    "params": {
      "name": "catalog_123_abc_def"
    }
  },
  "data": {
    "id": "1559934724822351872",
    "name": "catalog_123_abc_def"
  }
}
```

--------------------------------

### Create Manual Product Set Request

Source: https://docs.x.com/x-ads-api/catalog-management/reference

Endpoint and body structure for creating a product set using the MANUAL type.

```http
POST https://ads-api.x.com/12/product_catalogs/1569782857975087104/product_sets
```

```json
{
  "name": "manual API product set",
  "type": "MANUAL",
  "product_keys": [
    "1569784751351013380"
  ]
}
```

--------------------------------

### Create Funding Instrument Request

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example POST request to the sandbox environment for creating an insertion order funding instrument.

```http
POST https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments?currency=USD&start_time=2017-07-10T00:00:00Z&type=INSERTION_ORDER&end_time=2018-01-10T00:00:00Z&funded_amount_local_micro=140000000000
```

--------------------------------

### Verifying Creative Asset Metadata

Source: https://docs.x.com/x-ads-api/creatives

Commands and output examples to verify that XMP metadata has been correctly applied to an image.

```bash
exiftool -xmp:all -G1 <filename>
```

```bash
exiftool -xmp:all -G1 eiffel_tower.jpg
```

```json
[XMP]         XMP Toolkit         : Image::ExifTool 12.30
```

```json
[XMP]         Contributor         : 858382169
```

```json
[XMP]         Date                : 2022:03:13
```

--------------------------------

### Retrieve Custom Audience Permissions Request

Source: https://docs.x.com/x-ads-api/audiences/reference

Example GET request to fetch permissions for a specific custom audience.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions
```

--------------------------------

### Retrieve a specific tracking tag

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example response for a GET request to fetch details of a single tracking tag by its ID.

```json
{
      "request": {
        "params": {
          "with_deleted": true,
          "tracking_tag_id": "555j",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "72v2x",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N6344.2061500TWITTER-OFFICIAL/B23028778.279118262;dc_trk_aid=473354132;dc_trk_cid=119658253",
        "tracking_tag_type": "IMPRESSION_TAG",
        "id": "555j",
        "created_at": "2020-08-13T23:02:03Z",
        "updated_at": "2020-08-13T23:02:03Z",
        "deleted": false
      }
    }
```

--------------------------------

### Campaign Creation Response

Source: https://docs.x.com/x-ads-api/campaign-management

Example JSON response returned after successfully creating a new campaign.

```json
{
  "data": {
    "created_at": "2015-02-09T00:00:00Z",
    "currency": "USD",
    "daily_budget_amount_local_micro": 50000000,
    "deleted": false,
    "end_time": null,
    "funding_instrument_id": "yyyy",
    "id": "92ph",
    "name": "My First Campaign",
    "entity_status": "PAUSED",
    "standard_delivery": true,
    "total_budget_amount_local_micro": 500000000,
    "updated_at": "2015-02-09T00:00:00Z"
  },
  "data_type": "campaign",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "daily_budget_amount_local_micro": 50000000,
      "funding_instrument_id": "yyyy",
      "name": "My First Campaign",
      "total_budget_amount_local_micro": 500000000
    }
  }
}
```

--------------------------------

### Retrieve tracking tags for an account

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example response for a GET request to fetch tracking tags, optionally filtered by ID.

```json
{
      "request": {
        "params": {
          "tracking_tag_ids": [
            "3m82"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "fdwcl",
          "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
          "tracking_tag_type": "IMPRESSION_TAG",
          "id": "3m82",
          "created_at": "2019-06-26T17:04:26Z",
          "updated_at": "2019-06-26T17:04:26Z",
          "deleted": false
        }
      ]
    }
```

--------------------------------

### Retrieve Targeting Criterion Request

Source: https://docs.x.com/x-ads-api/campaign-management/reference

Example GET request to fetch a specific targeting criterion by account and criterion ID.

```http
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/eijd4y
```
Tokens:
Raw